@flow-industries/id 0.6.0 → 0.7.1

package/dist/sdk/client/create-flow.js

@@ -1,6 +1,7 @@
 import { createDialogHost } from "./dialog-host";
 import { idb } from "./idb";
 import { METHODS } from "./methods";
+import { makeRefreshStore } from "./refresh-store";
 import { credentialToAddress, restoreCredential, runLogin, runLogout, } from "./session";
 import { createStore, initialFlowState } from "./store";
 const DEFAULT_HOST = "https://id.flow.industries";
@@ -91,6 +92,7 @@ export function createFlow(options = {}) {
         return currentFlow;
     const host = (options.host ?? DEFAULT_HOST).replace(/\/+$/, "");
     const dialogUrl = `${host}/dialog/`;
+    const refreshStore = makeRefreshStore(host);
     const chains = options.chains ?? [];
     const getChain = (chainId) => {
         if (chainId == null)
@@ -120,19 +122,39 @@ export function createFlow(options = {}) {
      * user has no active session (in which case the caller should fall back to
      * `flow.login()`). Never throws — restore failures are treated as "no session".
      */
-    async function restore() {
-        const dialogHost = getDialog();
+    /**
+     * Mints a fresh session from the first-party refresh token: POSTs it as a
+     * bearer to /api/session/refresh (no cookie, so iOS ITP can't block it),
+     * commits the returned session, and persists the rotated token. Returns false
+     * (never throws) when there's no token or the server rejects it — the caller
+     * then falls back to ensureGuest()/login(). A 401 means the token is dead
+     * (expired, revoked, or reuse-detected), so it's dropped.
+     */
+    async function refreshViaToken() {
+        const token = refreshStore.get();
+        if (!token)
+            return false;
         try {
-            const result = await dialogHost.requestSilent(METHODS.restore, []);
+            const res = await fetch(`${host}/api/session/refresh`, {
+                method: "POST",
+                headers: { Authorization: `Bearer ${token}` },
+            });
+            if (!res.ok) {
+                if (res.status === 401)
+                    refreshStore.clear();
+                return false;
+            }
+            const result = (await res.json());
+            refreshStore.set(result.refreshToken);
             store.setState({
                 user: result.user,
                 jwt: result.jwt,
                 credential: result.credential,
                 address: result.address,
             });
-            // A guest restore returns a null credential; never persist that — the IDB
-            // store is reserved for a real passkey credential and writing null would
-            // erase a previously stored one.
+            // A guest carries a null credential; never persist that — the IDB store is
+            // reserved for a real passkey credential and writing null would erase a
+            // previously stored one.
             if (result.credential) {
                 await idb.set("flow.activeCredential", result.credential);
             }
@@ -142,10 +164,24 @@ export function createFlow(options = {}) {
             return false;
         }
     }
-    // refreshJwt is semantically the same as restore — both mint a fresh JWT
-    // from the cookie session. We expose two names because consumers reach for
-    // one or the other based on intent (page-load vs near-expiry).
-    const refreshJwt = restore;
+    // Every refresh-token POST — boot, ensureGuest, and getToken — funnels through
+    // this one lock so two callers can't present the same stored token at once.
+    // Rotation is single-use: a token replayed after it rotated looks like theft,
+    // tripping server-side reuse detection and revoking the whole lineage (which
+    // would then 401 → clear → re-guest). The lock serializes refreshes across
+    // tabs of the same origin, and the guard short-circuits a caller that arrives
+    // after a concurrent holder already minted a fresh JWT, so no one re-presents
+    // an already-rotated token. refreshViaToken re-reads the token fresh from
+    // storage inside the lock, so a genuinely-second refresh uses the rotated one.
+    async function doRefresh() {
+        return withGuestLock(`flow.id.refresh:${host}`, async () => {
+            const current = store.getSnapshot().jwt;
+            if (current && !isExpiring(current))
+                return true;
+            return refreshViaToken();
+        });
+    }
+    const refreshJwt = doRefresh;
     // Dedupe concurrent refreshes: a burst of getToken() calls that all find the
     // cached token expired should trigger one mint, not one per call.
     let refreshInFlight = null;
@@ -192,17 +228,18 @@ export function createFlow(options = {}) {
             return true;
         if (!guestInFlight) {
             guestInFlight = withGuestLock(`flow.id.guest:${host}`, async () => {
-                // Re-check under the lock: another tab may have minted the guest (and
-                // set the shared id.flow.industries cookie) while we waited, so
-                // restore-first collapses concurrent first-visits onto one row.
+                // Re-check under the lock: another tab may have minted the guest while
+                // we waited. Refresh-first (from this origin's stored token) recovers an
+                // existing session instead of minting a duplicate guest.
                 if (store.getSnapshot().user)
                     return true;
-                if (await restore())
+                if (await doRefresh())
                     return true;
                 try {
                     const result = await getDialog().requestSilent(METHODS.guest, []);
                     if (!result.user)
                         return false;
+                    refreshStore.set(result.refreshToken);
                     store.setState({
                         user: result.user,
                         jwt: result.jwt,
@@ -225,10 +262,10 @@ export function createFlow(options = {}) {
     void (async () => {
         await restoreCredential(store);
         if (options.autoRestore !== false) {
-            const restored = await restore();
-            // ensureGuest re-checks under a cross-tab lock (restore-first) before
-            // minting, so calling it after a failed restore can't fork a visitor into
-            // duplicate guests across tabs — the extra restore is the dedup.
+            const restored = await doRefresh();
+            // ensureGuest re-checks (refresh-first) under a cross-tab lock before
+            // minting, so calling it after a failed refresh can't fork a visitor into
+            // duplicate guests across tabs — the extra refresh is the dedup.
             if (!restored && options.autoGuest)
                 await ensureGuest();
         }
@@ -270,12 +307,13 @@ export function createFlow(options = {}) {
             accessKeyPrep = await accessKeyModule.prepareAccessKey(accessKeyOptions, chain.id);
             extraCapabilities = { accessKeyHash: accessKeyPrep.accessKeyHash };
         }
-        const { session, webauthn } = await runLogin({
+        const { session, webauthn, refreshToken } = await runLogin({
             dialog: dialogHost,
             store,
             options: loginOpts,
             ...(extraCapabilities ? { extraCapabilities } : {}),
         });
+        refreshStore.set(refreshToken);
         if (accessKeyModule && accessKeyPrep && webauthn) {
             await accessKeyModule.finalizeAccessKey({
                 address: session.address,
@@ -310,6 +348,7 @@ export function createFlow(options = {}) {
             // Server-side sign-out failed (offline?) — still clear local state.
         }
         await runLogout(store);
+        refreshStore.clear();
         dialog?.close();
         // An autoGuest app is never truly "signed out" — it always wants at least a
         // guest session. Re-mint one so the UI (e.g. the profile widget pill) keeps
@@ -338,7 +377,7 @@ export function createFlow(options = {}) {
         },
         login,
         logout,
-        restore,
+        restore: refreshJwt,
         ensureGuest,
         refreshJwt,
         getToken,

package/dist/sdk/client/methods.d.ts

@@ -4,7 +4,6 @@ export declare const METHODS: {
     readonly signTypedData: "eth_signTypedData";
     readonly sendTransaction: "eth_sendTransaction";
     readonly sendCalls: "wallet_sendCalls";
-    readonly restore: "wallet_restore";
     readonly guest: "wallet_guest";
     readonly signOut: "wallet_signout";
 };

package/dist/sdk/client/methods.js

@@ -4,7 +4,6 @@ export const METHODS = {
     signTypedData: "eth_signTypedData",
     sendTransaction: "eth_sendTransaction",
     sendCalls: "wallet_sendCalls",
-    restore: "wallet_restore",
     guest: "wallet_guest",
     signOut: "wallet_signout",
 };

package/dist/sdk/client/refresh-store.d.ts

@@ -0,0 +1,13 @@
+/**
+ * First-party persistence for the rotating refresh token. It lives in the
+ * consumer app's OWN localStorage (origin-scoped), so it survives reloads and
+ * navigations and — unlike the old id.flow.industries cookie — is never a
+ * third-party cookie, so iOS ITP can't block it. Keyed by `host` so pointing
+ * the SDK at a different Flow ID origin (dev vs prod) doesn't collide.
+ */
+export interface RefreshStore {
+    get(): string | null;
+    set(token: string): void;
+    clear(): void;
+}
+export declare function makeRefreshStore(host: string): RefreshStore;

package/dist/sdk/client/refresh-store.js

@@ -0,0 +1,25 @@
+export function makeRefreshStore(host) {
+    const key = `flow.id.refresh:${host}`;
+    return {
+        get() {
+            try {
+                return localStorage.getItem(key);
+            }
+            catch {
+                return null;
+            }
+        },
+        set(token) {
+            try {
+                localStorage.setItem(key, token);
+            }
+            catch { }
+        },
+        clear() {
+            try {
+                localStorage.removeItem(key);
+            }
+            catch { }
+        },
+    };
+}

package/dist/sdk/client/session.js

@@ -40,12 +40,13 @@ export async function runLogin(params) {
     const result = (await dialog.request(METHODS.connect, [
         { capabilities },
     ]));
-    const { jwt, user, credential, webauthn } = result;
+    const { jwt, refreshToken, user, credential, webauthn } = result;
     const address = credentialToAddress(credential);
     await idb.set(CREDENTIAL_KEY, credential);
     store.setState({ user, jwt, credential, address });
     return {
         session: { user, jwt, credential, address },
+        refreshToken,
         webauthn,
     };
 }

package/dist/sdk/types/auth.d.ts

@@ -16,6 +16,7 @@ export type FlowCredential = {
 };
 export type AuthResponse = {
     jwt: string;
+    refreshToken: string;
     user: FlowUser;
     credential: FlowCredential;
 };

package/dist/sdk/types/events.d.ts

@@ -8,8 +8,8 @@ export type AuthOutcome = "success" | "failure" | "info";
 export type AuthMode = "sign-up" | "sign-in";
 /** Client-only funnel steps reported via the `/api/events` beacon. */
 export type FunnelStep = "mode_selected" | "email_entered" | "ceremony_started" | "done_shown";
-export type AuthEventName = "auth.username.checked" | "auth.signup.succeeded" | "auth.signup.failed" | "auth.otp.sent" | "auth.otp.verified" | "auth.otp.failed" | "auth.email.verify.sent" | "auth.email.verify.succeeded" | "auth.email.verify.failed" | "auth.email.changed" | "auth.avatar.upload.succeeded" | "auth.avatar.upload.failed" | "auth.challenge.issued" | "auth.signin.succeeded" | "auth.signin.failed" | "auth.restore.succeeded" | "auth.restore.failed" | "auth.restore.no_session" | "auth.jwt.verified" | "auth.jwt.rejected" | "auth.signout" | "auth.audience.rejected" | "auth.guest.created" | "auth.guest.restored" | "auth.guest.upgraded" | "auth.guest.failed" | "auth.funnel.mode_selected" | "auth.funnel.email_entered" | "auth.funnel.ceremony_started" | "auth.funnel.done_shown";
-export type AuthErrorCode = "username_taken" | "credential_taken" | "email_taken" | "email_not_verified" | "no_email" | "image_upload_forbidden" | "image_upload_rate_limited" | "invalid_image_type" | "image_too_large" | "image_upload_failed" | "otp_invalid" | "otp_expired" | "otp_attempts_exceeded" | "otp_resend_cooldown" | "otp_resend_limit" | "otp_global_limit" | "otp_send_failed" | "challenge_expired" | "unknown_credential" | "invalid_assertion_type" | "invalid_assertion_origin" | "user_verification_required" | "invalid_signature" | "user_not_found" | "missing_audience" | "audience_not_allowed" | "audience_mismatch" | "no_session" | "no_passkey" | "guest_rate_limited" | "guest_global_limit" | "guest_username_exhausted" | "already_upgraded" | "malformed_token" | "unknown_key" | "verification_failed" | "internal_error";
+export type AuthEventName = "auth.username.checked" | "auth.signup.succeeded" | "auth.signup.failed" | "auth.otp.sent" | "auth.otp.verified" | "auth.otp.failed" | "auth.email.verify.sent" | "auth.email.verify.succeeded" | "auth.email.verify.failed" | "auth.email.changed" | "auth.avatar.upload.succeeded" | "auth.avatar.upload.failed" | "auth.challenge.issued" | "auth.signin.succeeded" | "auth.signin.failed" | "auth.restore.succeeded" | "auth.restore.failed" | "auth.restore.no_session" | "auth.refresh.succeeded" | "auth.refresh.failed" | "auth.refresh.reuse" | "auth.jwt.verified" | "auth.jwt.rejected" | "auth.signout" | "auth.audience.rejected" | "auth.guest.created" | "auth.guest.restored" | "auth.guest.upgraded" | "auth.guest.failed" | "auth.funnel.mode_selected" | "auth.funnel.email_entered" | "auth.funnel.ceremony_started" | "auth.funnel.done_shown";
+export type AuthErrorCode = "username_taken" | "credential_taken" | "email_taken" | "email_not_verified" | "no_email" | "image_upload_forbidden" | "image_upload_rate_limited" | "invalid_image_type" | "image_too_large" | "image_upload_failed" | "otp_invalid" | "otp_expired" | "otp_attempts_exceeded" | "otp_resend_cooldown" | "otp_resend_limit" | "otp_global_limit" | "otp_send_failed" | "challenge_expired" | "unknown_credential" | "invalid_assertion_type" | "invalid_assertion_origin" | "user_verification_required" | "invalid_signature" | "user_not_found" | "missing_audience" | "audience_not_allowed" | "audience_mismatch" | "no_session" | "no_passkey" | "refresh_token_invalid" | "refresh_token_expired" | "refresh_reuse_detected" | "guest_rate_limited" | "guest_global_limit" | "guest_username_exhausted" | "already_upgraded" | "malformed_token" | "unknown_key" | "verification_failed" | "internal_error";
 /** One flat record per event = one row in the `auth_events` stream. */
 export interface AuthEventRecord {
     service: "auth";

package/dist/sdk/types/index.d.ts

@@ -2,7 +2,8 @@ export type { AuthConfig, AuthResponse, AuthResponseWithWebAuthn, FlowCredential
 export type { BoundaryError, DialogCustomFeatures, DialogCustomLabels, DialogError, DialogReferrer, DialogState, ProfileData, ProfileIdentity, } from "./dialog";
 export type { AuthErrorCode, AuthEventName, AuthEventRecord, AuthMode, AuthOutcome, BeaconBody, FunnelStep, } from "./events";
 export type { Bridge, BridgeParameters, FlowAccount, FlowRemote, FlowRemoteConfig, FromWindowOptions, MessageResponse, Messenger, OneOf, Payload, QueuedRequest, ReadyOptions, RemoteFlowState, RemoteState, Schema, Storage, Topic, WithReady, } from "./messenger";
-export type { Call, ConnectCapabilities, ConnectRequest, ConnectResponse, GuestRequest, GuestResponse, MethodName, MethodParams, MethodResult, RestoreRequest, RestoreResponse, RpcRequest, SendCallsParams, SendCallsRequest, SendCallsResponse, SendTransactionParams, SendTransactionRequest, SendTransactionResponse, SignMessageRequest, SignMessageResponse, SignOutRequest, SignOutResponse, SignTypedDataRequest, SignTypedDataResponse, TransactionArgs, TypedData, TypedDataDomain, TypedDataField, } from "./protocol";
+export type { Call, ConnectCapabilities, ConnectRequest, ConnectResponse, GuestRequest, GuestResponse, MethodName, MethodParams, MethodResult, RestoreResponse, RpcRequest, SendCallsParams, SendCallsRequest, SendCallsResponse, SendTransactionParams, SendTransactionRequest, SendTransactionResponse, SignMessageRequest, SignMessageResponse, SignOutRequest, SignOutResponse, SignTypedDataRequest, SignTypedDataResponse, TransactionArgs, TypedData, TypedDataDomain, TypedDataField, } from "./protocol";
 export { isPersonalSignParams, isSendCallsParams, isSendTransactionParams, } from "./protocol";
 export type { AccessKeyOptions, AccessKeyPreparation, Address, CreateDialogHostOptions, CreateFlowOptions, DialogHost, DialogOpenOptions, FinalizeAccessKeyParams, Flow, FlowConnectorParameters, FlowIdProviderProps, FlowState, Listener, LoginOptions, MountProfileOptions, PrepareArgsWithAuth, PrepareTransactionRequestPhase, ProfileButtonHandle, ProfileButtonProps, ProfilePosition, ResolveAccountParams, ResolvedAccessKeyOptions, RootCredential, RunLoginParams, RunLoginResult, SendCallsArgs, SendTransactionArgs, Session, SigningContext, SignMessageArgs, SignTypedDataArgs, Store, StoredAccessKey, WagmiConnectCapabilities, WagmiConnectParams, } from "./sdk";
 export type { CoinAsset, IdentifiedTx, TxApprove, TxConvert, TxSend, TxSwap, } from "./tx";
+export type { ActionDayContext, ActionEventKind, ActionSessionState, ActiveActionResponse, LevelProgress, PublicProfile, XpGrantResult, XpRecentGrant, XpSummary, } from "./xp";

package/dist/sdk/types/protocol.d.ts

@@ -1,6 +1,6 @@
 import type { FlowCredential, FlowUser, WebAuthnSignature } from "./auth";
 import type { Address } from "./sdk";
-export type MethodName = "wallet_connect" | "personal_sign" | "eth_signTypedData" | "eth_sendTransaction" | "wallet_sendCalls" | "wallet_restore" | "wallet_guest" | "wallet_signout";
+export type MethodName = "wallet_connect" | "personal_sign" | "eth_signTypedData" | "eth_sendTransaction" | "wallet_sendCalls" | "wallet_guest" | "wallet_signout";
 export type ConnectCapabilities = {
     createAccount?: boolean;
     signIn?: boolean;
@@ -13,6 +13,8 @@ export type ConnectRequest = [{
 }];
 export type ConnectResponse = {
     jwt: string;
+    /** First-party rotating refresh token; the SDK persists it in the app origin. */
+    refreshToken: string;
     user: FlowUser;
     credential: FlowCredential;
     webauthn?: WebAuthnSignature;
@@ -58,12 +60,12 @@ export type SendCallsRequest = [
 export type SendCallsResponse = {
     id: string;
 };
-export type RestoreRequest = [];
 export type RestoreResponse = {
     jwt: string;
+    refreshToken: string;
     user: FlowUser;
-    credential: FlowCredential;
-    address: Address;
+    credential: FlowCredential | null;
+    address: Address | null;
 };
 export type GuestRequest = [];
 /**
@@ -73,6 +75,7 @@ export type GuestRequest = [];
  */
 export type GuestResponse = {
     jwt: string;
+    refreshToken: string;
     user: FlowUser;
     credential: null;
     address: null;
@@ -87,7 +90,6 @@ export type MethodParams = {
     eth_signTypedData: SignTypedDataRequest;
     eth_sendTransaction: SendTransactionRequest;
     wallet_sendCalls: SendCallsRequest;
-    wallet_restore: RestoreRequest;
     wallet_guest: GuestRequest;
     wallet_signout: SignOutRequest;
 };
@@ -97,7 +99,6 @@ export type MethodResult = {
     eth_signTypedData: SignTypedDataResponse;
     eth_sendTransaction: SendTransactionResponse;
     wallet_sendCalls: SendCallsResponse;
-    wallet_restore: RestoreResponse;
     wallet_guest: GuestResponse;
     wallet_signout: SignOutResponse;
 };

package/dist/sdk/types/sdk.d.ts

@@ -255,6 +255,7 @@ export type RunLoginParams = {
 };
 export type RunLoginResult = {
     session: Session;
+    refreshToken: string;
     webauthn: ConnectResponse["webauthn"];
 };
 export type FinalizeAccessKeyParams = {

package/dist/sdk/types/xp.d.ts

@@ -0,0 +1,72 @@
+/** XP / leveling shapes that cross the server/dialog boundary. */
+export interface LevelProgress {
+    /** Level within the current tier, 1..100 — it resets to 1 on each tier-up. */
+    level: number;
+    /** Prestige tier, 1..5. Reaching level 100 rolls into the next tier. */
+    tier: number;
+    /** XP earned since reaching the current level. */
+    xpIntoLevel: number;
+    /** XP between the current level's floor and the next level's floor. */
+    xpForNextLevel: number;
+}
+/** One recent ledger grant. Carries only the static source id — the display
+ * label resolves client-side from the registry, so renames never touch stored
+ * rows or the wire shape. */
+export interface XpRecentGrant {
+    source: string;
+    amount: number;
+    /** ISO timestamp of the grant, for newer-than-last-seen diffing. */
+    at: string;
+}
+/** Response shape of GET /api/xp/me. */
+export interface XpSummary extends LevelProgress {
+    totalXp: number;
+    flowScore: number;
+    /** Last few positive grants, newest first. Optional so client-synthesized
+     * summaries (the widget's per-frame lerp) stay valid without it. */
+    recentGrants?: XpRecentGrant[];
+}
+/** Outcome of one grant attempt. `granted: false` covers idempotent replays,
+ * sub-minimum durations and exhausted daily caps — all non-errors. Carries the
+ * post-grant standing so reporters (the game server) can refresh a player's
+ * nametag level without a second request. */
+export interface XpGrantResult extends LevelProgress {
+    granted: boolean;
+    amount: number;
+    totalXp: number;
+    flowScore: number;
+}
+/** Response of GET /api/xp/day/:source — what the in-game action timer needs to
+ * estimate a live session's XP: today's prior minutes for the source (so the
+ * day-cumulative curve starts from the right point) and the flow multiplier. */
+export interface ActionDayContext {
+    priorMinutes: number;
+    flowScore: number;
+}
+/** Lifecycle state of a durable action session. `abandoned` is set by the
+ * orphan reaper when the game server stops heartbeating a still-active
+ * session (e.g. a server crash). */
+export type ActionSessionState = "active" | "finished" | "abandoned";
+/** An action-session transition kind, appended to the action_event log.
+ * `focus_lost`/`focus_gained` mark the tab going background/foreground — accrual
+ * never stops (they only split focused vs unfocused time for stats). */
+export type ActionEventKind = "start" | "focus_lost" | "focus_gained" | "finish" | "abandon";
+/** Response of GET /api/actions/active — the caller's current in-progress
+ * action (or null when idle), plus the day context so the timer can render the
+ * live XP estimate from the server-authoritative accrued duration. (Always an
+ * `active` session by definition, so the lifecycle state isn't carried.) */
+export interface ActiveActionResponse extends ActionDayContext {
+    source: string;
+    label: string | null;
+    accruedSeconds: number;
+}
+/** Non-sensitive profile facts any player may see about another — nested into
+ * the /api/session/verify payload beside `appearance` so game servers can
+ * broadcast them (avatar + level badge on nametags) without extra fetches.
+ * snake_case keys to match the appearance object in the same payload; the
+ * Godot consumer parses both symmetrically. */
+export interface PublicProfile {
+    avatar_url: string | null;
+    tier: number;
+    level: number;
+}

package/dist/sdk/types/xp.js

@@ -0,0 +1 @@
+/** XP / leveling shapes that cross the server/dialog boundary. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flow-industries/id",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "main": "./dist/sdk/client/index.js",
   "module": "./dist/sdk/client/index.js",
   "types": "./dist/sdk/client/index.d.ts",
@@ -53,6 +53,7 @@
     "db:push": "bunx drizzle-kit push",
     "db:studio": "bunx drizzle-kit studio",
     "lint": "biome check",
+    "test": "bun test src",
     "format": "biome format --write",
     "check": "biome check --write",
     "typecheck": "tsr generate && tsc --noEmit"