@flow-industries/id 0.3.0 → 0.4.0

package/dist/sdk/client/access-key.d.ts

@@ -1,5 +1,5 @@
 import { Account } from "viem/tempo";
-import type { AccessKeyPreparation, Address as Hex, FinalizeAccessKeyParams, FlowCredential, ResolvedAccessKeyOptions, StoredAccessKey } from "../types";
+import type { AccessKeyPreparation, FinalizeAccessKeyParams, FlowCredential, Address as Hex, ResolvedAccessKeyOptions, StoredAccessKey } from "../types";
 /**
  * Step 1 of access-key creation — runs BEFORE the dialog opens.
  *
@@ -7,8 +7,10 @@ import type { AccessKeyPreparation, Address as Hex, FinalizeAccessKeyParams, Flo
  * and builds an unsigned KeyAuthorization that grants this key permission to
  * sign on behalf of the root account until `expiry`. Returns the key pair
  * plus a signing payload (`accessKeyHash`) that gets passed into the dialog
- * so the same WebAuthn ceremony that signs the user in also signs the
- * authorization — saving a second tap.
+ * so the user's passkey can authorize it. The dialog signs `accessKeyHash`
+ * in its own WebAuthn ceremony, separate from login — Tempo's on-chain
+ * verifier requires a signature over this exact digest, so it cannot be
+ * folded into the login challenge.
  *
  * Pairs with `finalizeAccessKey()` after the dialog returns the WebAuthn
  * signature.

package/dist/sdk/client/access-key.js

@@ -1,7 +1,7 @@
-import { Account, WebCryptoP256 } from "viem/tempo";
-import { KeyAuthorization, SignatureEnvelope } from "ox/tempo";
 import * as Address from "ox/Address";
 import * as PublicKey from "ox/PublicKey";
+import { KeyAuthorization, SignatureEnvelope } from "ox/tempo";
+import { Account, WebCryptoP256 } from "viem/tempo";
 import { idb } from "./idb";
 /**
  * Step 1 of access-key creation — runs BEFORE the dialog opens.
@@ -10,8 +10,10 @@ import { idb } from "./idb";
  * and builds an unsigned KeyAuthorization that grants this key permission to
  * sign on behalf of the root account until `expiry`. Returns the key pair
  * plus a signing payload (`accessKeyHash`) that gets passed into the dialog
- * so the same WebAuthn ceremony that signs the user in also signs the
- * authorization — saving a second tap.
+ * so the user's passkey can authorize it. The dialog signs `accessKeyHash`
+ * in its own WebAuthn ceremony, separate from login — Tempo's on-chain
+ * verifier requires a signature over this exact digest, so it cannot be
+ * folded into the login challenge.
  *
  * Pairs with `finalizeAccessKey()` after the dialog returns the WebAuthn
  * signature.

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

@@ -4,6 +4,43 @@ import { METHODS } from "./methods";
 import { credentialToAddress, restoreCredential, runLogin, runLogout, } from "./session";
 import { createStore, initialFlowState } from "./store";
 const DEFAULT_HOST = "https://id.flow.industries";
+// Refresh a little before the JWT's `exp` so a token handed out by getToken()
+// is still valid by the time it reaches the relying party, absorbing request
+// latency and minor client/server clock skew.
+const EXPIRY_SKEW_MS = 60_000;
+/** Reads the `exp` (seconds since epoch) from a JWT, or null if unreadable. */
+function jwtExp(token) {
+    const parts = token.split(".");
+    if (parts.length !== 3)
+        return null;
+    try {
+        const padded = parts[1].replace(/-/g, "+").replace(/_/g, "/");
+        const payload = JSON.parse(atob(padded));
+        return typeof payload.exp === "number" ? payload.exp : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** True if the token is missing an exp, already expired, or within the skew. */
+function isExpiring(token) {
+    const exp = jwtExp(token);
+    if (exp === null)
+        return true;
+    return Date.now() >= exp * 1000 - EXPIRY_SKEW_MS;
+}
+/**
+ * Runs `fn` while holding a cross-tab lock (Web Locks API) so concurrent tabs
+ * of the same origin serialize guest creation: the first tab mints and sets the
+ * shared cookie, later tabs then restore it instead of minting a duplicate
+ * guest. Falls back to running `fn` directly where Web Locks is unavailable.
+ */
+function withGuestLock(name, fn) {
+    const locks = globalThis.navigator?.locks;
+    if (locks?.request)
+        return locks.request(name, fn);
+    return fn();
+}
 /**
  * Normalizes user-supplied access-key configuration into a fully-resolved
  * shape. Accepts `true` for defaults, a partial options object, or omitted
@@ -93,7 +130,12 @@ export function createFlow(options = {}) {
                 credential: result.credential,
                 address: result.address,
             });
-            await idb.set("flow.activeCredential", result.credential);
+            // 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.
+            if (result.credential) {
+                await idb.set("flow.activeCredential", result.credential);
+            }
             return true;
         }
         catch {
@@ -104,10 +146,94 @@ export function createFlow(options = {}) {
     // 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;
+    // 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;
+    /**
+     * Returns a currently-valid JWT, silently minting a fresh one from the
+     * 60-day cookie session when the cached token is missing, expired, or within
+     * EXPIRY_SKEW_MS of expiring. This is the accessor to call before hitting a
+     * relying-party backend: the JWT is a 1h access token, so reading the cached
+     * `flow.jwt` from a tab open longer than an hour would send a stale token.
+     *
+     * The refresh is silent (cookie-based, no passkey prompt). Returns null only
+     * when there is no usable session — the caller should then prompt
+     * `flow.login()`. Use it inside a 401 handler too: `await flow.getToken()`
+     * before retrying the request.
+     */
+    async function getToken() {
+        const current = store.getSnapshot().jwt;
+        if (current && !isExpiring(current))
+            return current;
+        if (!refreshInFlight) {
+            refreshInFlight = refreshJwt().finally(() => {
+                refreshInFlight = null;
+            });
+        }
+        await refreshInFlight;
+        const next = store.getSnapshot().jwt;
+        return next && !isExpiring(next) ? next : null;
+    }
+    // Single-flight within this instance; the cross-tab lock below extends the
+    // dedup across tabs of the same origin.
+    let guestInFlight = null;
+    /**
+     * Ensures a session exists, silently creating a persistent guest when none
+     * does. Idempotent and never throws (a failed mint resolves false so the
+     * caller can fall back to flow.login()).
+     *
+     * Restore-first under a cross-tab lock is the dedup: a returning or
+     * concurrently-minting visitor reuses their existing guest/full session
+     * instead of spawning a duplicate. The guest-mint branch writes only to the
+     * in-memory store (never IDB) — IDB is reserved for a real passkey credential.
+     */
+    async function ensureGuest() {
+        if (store.getSnapshot().user)
+            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.
+                if (store.getSnapshot().user)
+                    return true;
+                if (await restore())
+                    return true;
+                try {
+                    const result = await getDialog().requestSilent(METHODS.guest, []);
+                    if (!result.user)
+                        return false;
+                    store.setState({
+                        user: result.user,
+                        jwt: result.jwt,
+                        // Only a guest has no credential. The server's idempotency path can
+                        // return a full session here; in that case keep any credential/
+                        // address already in state rather than stripping signing.
+                        ...(result.user.isGuest ? { credential: null, address: null } : {}),
+                    });
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            }).finally(() => {
+                guestInFlight = null;
+            });
+        }
+        return guestInFlight;
+    }
     void (async () => {
         await restoreCredential(store);
         if (options.autoRestore !== false) {
-            await restore();
+            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.
+            if (!restored && options.autoGuest)
+                await ensureGuest();
+        }
+        else if (options.autoGuest) {
+            await ensureGuest();
         }
     })();
     function buildSigningContext() {
@@ -158,7 +284,12 @@ export function createFlow(options = {}) {
                 preparation: accessKeyPrep,
             });
         }
-        dialogHost.close();
+        // The dialog owns closing in every interactive path: sign-in sends "close"
+        // immediately after responding, sign-up after its brief "Welcome" screen.
+        // Closing here would preempt the welcome screen, and — since the gate can
+        // only see the caller's intent, not the flow the user actually completed —
+        // it fired even when a flow.login() user navigated to sign-up. So don't
+        // close from the connector; let the dialog decide.
         return session;
     }
     /**
@@ -197,10 +328,15 @@ export function createFlow(options = {}) {
         get isAuthenticated() {
             return store.getSnapshot().user !== null;
         },
+        get isGuest() {
+            return store.getSnapshot().user?.isGuest === true;
+        },
         login,
         logout,
         restore,
+        ensureGuest,
         refreshJwt,
+        getToken,
         signMessage: async (args) => {
             const mod = await import("./signing");
             return mod.signMessage(buildSigningContext(), args);

package/dist/sdk/client/dialog-host.js

@@ -47,7 +47,8 @@ export function createDialogHost(options) {
         iframe = document.createElement("iframe");
         iframe.src = `${host}`;
         iframe.dataset.flowId = "";
-        iframe.allow = "publickey-credentials-create; publickey-credentials-get; clipboard-write";
+        iframe.allow =
+            "publickey-credentials-create; publickey-credentials-get; clipboard-write";
         Object.assign(iframe.style, HIDDEN_STYLE);
         iframe.style.colorScheme = "normal";
         container.appendChild(iframe);

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

@@ -1,4 +1,4 @@
+export type { AccessKeyOptions, Address, ConnectCapabilities, ConnectResponse, CreateFlowOptions, DialogHost, Flow, FlowCredential, FlowState, FlowUser, LoginOptions, MethodName, Session, } from "../types";
 export { createFlow, getFlow, requireFlow, resetFlow } from "./create-flow";
 export { createDialogHost } from "./dialog-host";
 export { METHODS } from "./methods";
-export type { AccessKeyOptions, Address, ConnectCapabilities, ConnectResponse, CreateFlowOptions, DialogHost, Flow, FlowCredential, FlowState, FlowUser, LoginOptions, MethodName, Session, } from "../types";

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

@@ -5,5 +5,6 @@ export declare const METHODS: {
     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

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

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

@@ -1,5 +1,5 @@
 import { type Hex, type WalletClient } from "viem";
-import type { SendCallsArgs, SendTransactionArgs, SignMessageArgs, SignTypedDataArgs, SigningContext } from "../types";
+import type { SendCallsArgs, SendTransactionArgs, SigningContext, SignMessageArgs, SignTypedDataArgs } from "../types";
 /**
  * Constructs a viem WalletClient bound to the user's Flow account. Wraps the
  * transport in `walletNamespaceCompat` so Tempo's wallet RPC namespace is

package/dist/sdk/client/signing.js

@@ -108,7 +108,9 @@ export async function buildWalletClient(ctx, chainId) {
     return createWalletClient({
         account,
         chain: withAccessKeyAuthorization(chain, address),
-        transport: walletNamespaceCompat(transport, { account }),
+        transport: walletNamespaceCompat(transport, {
+            account,
+        }),
     });
 }
 export async function signMessage(ctx, args) {

package/dist/sdk/client/store.js

@@ -28,7 +28,10 @@ export const initialFlowState = {
 function shallowEqual(a, b) {
     if (a === b)
         return true;
-    if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) {
+    if (typeof a !== "object" ||
+        typeof b !== "object" ||
+        a === null ||
+        b === null) {
         return false;
     }
     const ak = Object.keys(a);

package/dist/sdk/dialog/remote/Messenger.d.ts

@@ -1,6 +1,5 @@
 import type { Bridge, BridgeParameters, FromWindowOptions, Messenger } from "../../types";
-export type { Bridge, BridgeParameters, FromWindowOptions, Messenger, Payload, QueuedRequest, ReadyOptions, Schema, Topic, WithReady, } from "../../types";
-export type { MessageResponse as Response } from "../../types";
+export type { Bridge, BridgeParameters, FromWindowOptions, MessageResponse as Response, Messenger, Payload, QueuedRequest, ReadyOptions, Schema, Topic, WithReady, } from "../../types";
 export declare function from(messenger: Messenger): Messenger;
 /**
  * Wraps a Window in the Messenger interface. Reads come from

package/dist/sdk/react/hooks.d.ts

@@ -18,16 +18,20 @@ export declare function useFlowState(): FlowState;
 /**
  * Convenience hook that returns the most commonly needed identity data and
  * actions in one go: user/jwt/address plus `login`, `logout`, `restore`,
- * and `refreshJwt`. The `isAuthenticated` boolean is derived from `user`
- * being set so it tracks reactive state.
+ * `refreshJwt`, and `getToken`. The `isAuthenticated` boolean is derived from
+ * `user` being set so it tracks reactive state; `isGuest` is true while the
+ * user is a guest — gate sensitive actions on `!isGuest`, not `isAuthenticated`.
  */
 export declare function useFlowId(): {
     user: import("../types").FlowUser | null;
     jwt: string | null;
     address: `0x${string}` | null;
     isAuthenticated: boolean;
+    isGuest: boolean;
     login: (options?: import("../types").LoginOptions) => Promise<import("../types").Session>;
     logout: () => Promise<void>;
     restore: () => Promise<boolean>;
+    ensureGuest: () => Promise<boolean>;
     refreshJwt: () => Promise<boolean>;
+    getToken: () => Promise<string | null>;
 };

package/dist/sdk/react/hooks.js

@@ -32,8 +32,9 @@ export function useFlowState() {
 /**
  * Convenience hook that returns the most commonly needed identity data and
  * actions in one go: user/jwt/address plus `login`, `logout`, `restore`,
- * and `refreshJwt`. The `isAuthenticated` boolean is derived from `user`
- * being set so it tracks reactive state.
+ * `refreshJwt`, and `getToken`. The `isAuthenticated` boolean is derived from
+ * `user` being set so it tracks reactive state; `isGuest` is true while the
+ * user is a guest — gate sensitive actions on `!isGuest`, not `isAuthenticated`.
  */
 export function useFlowId() {
     const flow = useFlow();
@@ -43,9 +44,12 @@ export function useFlowId() {
         jwt: state.jwt,
         address: state.address,
         isAuthenticated: state.user !== null,
+        isGuest: state.user?.isGuest ?? false,
         login: flow.login,
         logout: flow.logout,
         restore: flow.restore,
+        ensureGuest: flow.ensureGuest,
         refreshJwt: flow.refreshJwt,
+        getToken: flow.getToken,
     };
 }

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

@@ -1,3 +1,3 @@
-export { FlowIdProvider } from "./provider";
-export { useFlow, useFlowId, useFlowState } from "./hooks";
 export type { FlowIdProviderProps } from "../types";
+export { useFlow, useFlowId, useFlowState } from "./hooks";
+export { FlowIdProvider } from "./provider";

package/dist/sdk/react/index.js

@@ -1,2 +1,2 @@
-export { FlowIdProvider } from "./provider";
 export { useFlow, useFlowId, useFlowState } from "./hooks";
+export { FlowIdProvider } from "./provider";

package/dist/sdk/react/provider.js

@@ -11,5 +11,5 @@ export const FlowContext = createContext(null);
  * the dependency explicit at a particular boundary.
  */
 export function FlowIdProvider({ flow, children }) {
-    return _jsx(FlowContext.Provider, { value: flow ?? null, children: children });
+    return (_jsx(FlowContext.Provider, { value: flow ?? null, children: children }));
 }

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

@@ -2,6 +2,13 @@ import type { JWTPayload } from "jose";
 export type FlowUser = {
     id: string;
     username: string;
+    /**
+     * True only for guest accounts (no passkey/email yet). Optional so the many
+     * `{ id, username }` producers stay valid; readers treat `undefined`/`false`
+     * as "not a guest". Sensitive actions should gate on `!isGuest` (or the JWT
+     * `guest` claim), never on session presence alone.
+     */
+    isGuest?: boolean;
 };
 export type FlowCredential = {
     id: string;
@@ -42,4 +49,10 @@ export type VerifyOptions = {
 export type VerifiedFlowJWT = JWTPayload & {
     sub: string;
     username?: string;
+    /**
+     * Present and `true` only on guest tokens. A relying party gating sensitive
+     * actions MUST treat a MISSING claim as `guest === true` (fail-safe), so a
+     * future token-format change can never silently grant full privileges.
+     */
+    guest?: boolean;
 };

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

@@ -0,0 +1,40 @@
+/**
+ * Structured auth-observability events. Emitted server-side to the dedicated
+ * OpenObserve `auth_events` stream (and mirrored to stdout). The field names
+ * here are the contract every dashboard/alert query depends on — changing one
+ * is a breaking change to the dashboard.
+ */
+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.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" | "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";
+/** One flat record per event = one row in the `auth_events` stream. */
+export interface AuthEventRecord {
+    service: "auth";
+    env: string;
+    event: AuthEventName;
+    outcome: AuthOutcome;
+    app: string | null;
+    audience: string | null;
+    userId: string | null;
+    username: string | null;
+    address: string | null;
+    credentialId: string | null;
+    funnelId: string | null;
+    mode: AuthMode | null;
+    step: FunnelStep | null;
+    errorCode: AuthErrorCode | null;
+    ip: string | null;
+    country: string | null;
+    userAgent: string | null;
+    durationMs: number | null;
+    traceId: string | null;
+}
+/** Body accepted by `POST /api/events` from the dialog. */
+export interface BeaconBody {
+    step: FunnelStep;
+    funnelId: string;
+    mode?: AuthMode | null;
+}

package/dist/sdk/types/events.js

@@ -0,0 +1,6 @@
+/**
+ * Structured auth-observability events. Emitted server-side to the dedicated
+ * OpenObserve `auth_events` stream (and mirrored to stdout). The field names
+ * here are the contract every dashboard/alert query depends on — changing one
+ * is a breaking change to the dashboard.
+ */

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

@@ -1,7 +1,8 @@
 export type { AuthConfig, AuthResponse, AuthResponseWithWebAuthn, FlowCredential, FlowUser, PasskeyPluginOptions, VerifiedFlowJWT, VerifyOptions, WebAuthnSignature, } from "./auth";
-export type { AccessKeyOptions, AccessKeyPreparation, Address, CreateDialogHostOptions, CreateFlowOptions, DialogHost, DialogOpenOptions, FinalizeAccessKeyParams, Flow, FlowIdProviderProps, FlowConnectorParameters, FlowState, Listener, LoginOptions, PrepareArgsWithAuth, PrepareTransactionRequestPhase, ResolveAccountParams, ResolvedAccessKeyOptions, RootCredential, RunLoginParams, RunLoginResult, SendCallsArgs, SendTransactionArgs, Session, SignMessageArgs, SignTypedDataArgs, SigningContext, StoredAccessKey, Store, WagmiConnectCapabilities, WagmiConnectParams, } from "./sdk";
-export { isPersonalSignParams, isSendCallsParams, isSendTransactionParams, } from "./protocol";
-export type { Call, ConnectCapabilities, ConnectRequest, ConnectResponse, 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 { Bridge, BridgeParameters, FlowAccount, FlowRemote, FlowRemoteConfig, FromWindowOptions, MessageResponse, Messenger, OneOf, Payload, QueuedRequest, ReadyOptions, RemoteFlowState, RemoteState, Schema, Storage, Topic, WithReady, } from "./messenger";
 export type { BoundaryError, DialogCustomFeatures, DialogCustomLabels, DialogError, DialogReferrer, DialogState, } 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 { isPersonalSignParams, isSendCallsParams, isSendTransactionParams, } from "./protocol";
+export type { AccessKeyOptions, AccessKeyPreparation, Address, CreateDialogHostOptions, CreateFlowOptions, DialogHost, DialogOpenOptions, FinalizeAccessKeyParams, Flow, FlowConnectorParameters, FlowIdProviderProps, FlowState, Listener, LoginOptions, PrepareArgsWithAuth, PrepareTransactionRequestPhase, 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";

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_signout";
+export type MethodName = "wallet_connect" | "personal_sign" | "eth_signTypedData" | "eth_sendTransaction" | "wallet_sendCalls" | "wallet_restore" | "wallet_guest" | "wallet_signout";
 export type ConnectCapabilities = {
     createAccount?: boolean;
     signIn?: boolean;
@@ -65,6 +65,18 @@ export type RestoreResponse = {
     credential: FlowCredential;
     address: Address;
 };
+export type GuestRequest = [];
+/**
+ * A guest has no passkey and no derivable wallet address yet, so `credential`
+ * and `address` are always null — the shape mirrors RestoreResponse so the SDK
+ * can commit either to the same store fields.
+ */
+export type GuestResponse = {
+    jwt: string;
+    user: FlowUser;
+    credential: null;
+    address: null;
+};
 export type SignOutRequest = [];
 export type SignOutResponse = {
     ok: true;
@@ -76,6 +88,7 @@ export type MethodParams = {
     eth_sendTransaction: SendTransactionRequest;
     wallet_sendCalls: SendCallsRequest;
     wallet_restore: RestoreRequest;
+    wallet_guest: GuestRequest;
     wallet_signout: SignOutRequest;
 };
 export type MethodResult = {
@@ -85,6 +98,7 @@ export type MethodResult = {
     eth_sendTransaction: SendTransactionResponse;
     wallet_sendCalls: SendCallsResponse;
     wallet_restore: RestoreResponse;
+    wallet_guest: GuestResponse;
     wallet_signout: SignOutResponse;
 };
 export type RpcRequest = {

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

@@ -1,6 +1,6 @@
+import type { ReactNode } from "react";
 import type { Chain, Hex, PrepareTransactionRequestParameters, SendTransactionParameters, SignTypedDataParameters, Transport, WalletClient } from "viem";
 import type { SendCallsParameters } from "viem/actions";
-import type { ReactNode } from "react";
 import type { FlowCredential, FlowUser, WebAuthnSignature } from "./auth";
 import type { ConnectCapabilities, ConnectResponse } from "./protocol";
 export type Address = `0x${string}`;
@@ -63,6 +63,13 @@ export type CreateFlowOptions = {
      * if the user has a valid Flow cookie session, state populates without UI.
      */
     autoRestore?: boolean;
+    /**
+     * If true, every visitor without an existing session is silently given a
+     * persistent guest account on startup (no UI, no passkey). Off by default —
+     * the consumer app opts in. Signing up later upgrades the guest in place, so
+     * data keyed on the Flow user id survives. See `ensureGuest`.
+     */
+    autoGuest?: boolean;
 };
 export type FlowState = {
     user: FlowUser | null;
@@ -136,10 +143,29 @@ export type Flow = {
     readonly credential: FlowState["credential"];
     readonly address: Address | null;
     readonly isAuthenticated: boolean;
+    /**
+     * True when the current session is a guest (authenticated but not yet a full
+     * account). `isAuthenticated` is also true for guests — gate sensitive
+     * actions on `!isGuest`, not on `isAuthenticated`.
+     */
+    readonly isGuest: boolean;
     login(options?: LoginOptions): Promise<Session>;
     logout(): Promise<void>;
     restore(): Promise<boolean>;
+    /**
+     * Ensures a session exists: restores an existing one, otherwise silently
+     * creates a persistent guest account. Idempotent and single-flight; resolves
+     * true if a session (guest or full) is now active, false if creation failed.
+     * Called automatically on startup when `autoGuest` is set.
+     */
+    ensureGuest(): Promise<boolean>;
     refreshJwt(): Promise<boolean>;
+    /**
+     * Returns a currently-valid JWT, silently refreshing from the cookie session
+     * if the cached token is expired or near expiry; null if there is no session.
+     * Prefer this over reading `jwt` directly when calling a backend.
+     */
+    getToken(): Promise<string | null>;
     signMessage(args: SignMessageArgs): Promise<Hex>;
     signTypedData(args: SignTypedDataArgs): Promise<Hex>;
     sendTransaction(args: SendTransactionArgs): Promise<Hex>;

package/dist/sdk/verify.d.ts

@@ -11,5 +11,12 @@ export type { VerifiedFlowJWT, VerifyOptions } from "./types";
  *
  * `audience` MUST match the calling app's origin — this is what prevents
  * a token issued for `flow.talk` from being replayed against `flow.game`.
+ *
+ * Every Flow token carries an explicit boolean `guest` claim (`true` for guest
+ * sessions with no passkey yet, `false` for full accounts). When gating
+ * sensitive actions, require `payload.guest === false`; treat anything else —
+ * `true`, or a MISSING claim (not a Flow token, or a future format change) — as
+ * guest and deny. This fail-safe means a dropped or renamed claim can never
+ * silently grant a guest full privileges.
  */
 export declare function verifyFlowJWT(token: string, opts: VerifyOptions): Promise<VerifiedFlowJWT>;

package/dist/sdk/verify.js

@@ -12,6 +12,13 @@ const DEFAULT_ISSUER_URL = "https://id.flow.industries";
  *
  * `audience` MUST match the calling app's origin — this is what prevents
  * a token issued for `flow.talk` from being replayed against `flow.game`.
+ *
+ * Every Flow token carries an explicit boolean `guest` claim (`true` for guest
+ * sessions with no passkey yet, `false` for full accounts). When gating
+ * sensitive actions, require `payload.guest === false`; treat anything else —
+ * `true`, or a MISSING claim (not a Flow token, or a future format change) — as
+ * guest and deny. This fail-safe means a dropped or renamed claim can never
+ * silently grant a guest full privileges.
  */
 export async function verifyFlowJWT(token, opts) {
     const issuerUrl = opts.issuerUrl ?? DEFAULT_ISSUER_URL;

package/dist/sdk/wagmi/index.js

@@ -8,7 +8,8 @@ function loginOptionsFromCapabilities(capabilities) {
     return {
         ...(signUp ? { signUp: true } : {}),
         ...(!signUp && signIn ? { signIn: true } : {}),
-        ...(!signUp && (capabilities?.signInHeadless || capabilities?.type === "sign-in")
+        ...(!signUp &&
+            (capabilities?.signInHeadless || capabilities?.type === "sign-in")
             ? { signInHeadless: true }
             : {}),
     };
@@ -137,8 +138,12 @@ export function flowConnector(parameters = {}) {
                 return f.walletClient({ ...(chainId ? { chainId } : {}) });
             },
             async getProvider({ chainId } = {}) {
-                const client = await this.getClient({ ...(chainId ? { chainId } : {}) });
-                return { request: client.request };
+                const client = await this.getClient({
+                    ...(chainId ? { chainId } : {}),
+                });
+                return {
+                    request: client.request,
+                };
             },
             onAccountsChanged() { },
             onChainChanged(chain) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flow-industries/id",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "main": "./dist/sdk/client/index.js",
   "module": "./dist/sdk/client/index.js",
   "types": "./dist/sdk/client/index.d.ts",
@@ -46,10 +46,16 @@
     "build:sdk": "tsc --project tsconfig.sdk.json",
     "prepublishOnly": "bun run build:sdk",
     "start": "bun run src/index.ts",
+    "email:dev": "email dev --dir src/emails --port 3010",
     "db:generate": "bunx @better-auth/cli generate",
-    "db:migrate": "bunx drizzle-kit generate && bunx drizzle-kit migrate",
+    "db:migrate:gen": "bunx drizzle-kit generate",
+    "db:migrate": "bunx drizzle-kit migrate",
     "db:push": "bunx drizzle-kit push",
-    "db:studio": "bunx drizzle-kit studio"
+    "db:studio": "bunx drizzle-kit studio",
+    "lint": "biome check",
+    "format": "biome format --write",
+    "check": "biome check --write",
+    "typecheck": "tsr generate && tsc --noEmit"
   },
   "peerDependencies": {
     "viem": ">=2.47.10",
@@ -67,21 +73,38 @@
   },
   "devDependencies": {
     "@better-auth/cli": "^1.4.17",
+    "@biomejs/biome": "2.4.12",
+    "@flow-industries/lint": "0.1.0",
+    "@react-email/ui": "^6.6.0",
     "@tailwindcss/vite": "^4.1.18",
     "@tanstack/react-router-devtools": "^1.160.0",
+    "@tanstack/router-cli": "^1.167.17",
     "@tanstack/router-plugin": "^1.160.0",
     "@types/bun": "latest",
     "@types/react": "^19.2.13",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^5.1.3",
     "drizzle-kit": "^0.31.8",
+    "pino-pretty": "^13.1.3",
+    "react-email": "^6.6.0",
     "tailwindcss": "^4.1.18",
     "tw-animate-css": "^1.4.0",
     "typescript": "^5",
     "vite": "^7.3.1"
   },
   "dependencies": {
-    "@flow-industries/ui": "^0.15.2",
+    "@flow-industries/ui": "^0.15.3",
+    "@hono/otel": "^1.1.2",
+    "@openobserve/browser-logs": "^0.3.1",
+    "@openobserve/browser-rum": "^0.3.1",
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.218.0",
+    "@opentelemetry/resources": "^2.7.1",
+    "@opentelemetry/sdk-trace-base": "^2.7.1",
+    "@opentelemetry/sdk-trace-node": "^2.7.1",
+    "@opentelemetry/semantic-conventions": "^1.41.1",
+    "@react-email/components": "^1.0.12",
+    "@react-email/render": "^2.0.8",
     "@tanstack/query-sync-storage-persister": "^5.90.22",
     "@tanstack/react-query": "^5.90.20",
     "@tanstack/react-query-persist-client": "^5.90.22",
@@ -93,6 +116,7 @@
     "jose": "^6.1.3",
     "lucide-react": "^0.563.0",
     "motion": "^12.33.0",
+    "pino": "^10.3.1",
     "postgres": "^3.4.8",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",

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

@@ -1,97 +0,0 @@
-import type { FlowUser, FlowCredential, WebAuthnSignature } from "../types";
-export declare const METHODS: {
-    readonly connect: "wallet_connect";
-    readonly signMessage: "personal_sign";
-    readonly signTypedData: "eth_signTypedData";
-    readonly sendTransaction: "eth_sendTransaction";
-    readonly sendCalls: "wallet_sendCalls";
-    readonly restore: "wallet_restore";
-    readonly signOut: "wallet_signout";
-};
-export type Method = (typeof METHODS)[keyof typeof METHODS];
-export type ConnectCapabilities = {
-    createAccount?: boolean;
-    signIn?: boolean;
-    accessKeyHash?: string;
-    headless?: boolean;
-    credentialId?: string;
-};
-export type ConnectRequest = [{
-    capabilities?: ConnectCapabilities;
-}];
-export type ConnectResponse = {
-    jwt: string;
-    user: FlowUser;
-    credential: FlowCredential;
-    webauthn?: WebAuthnSignature;
-};
-export type SignMessageRequest = [message: string, address: string];
-export type SignMessageResponse = `0x${string}`;
-export type TypedDataDomain = {
-    name?: string;
-    version?: string;
-    chainId?: number;
-    verifyingContract?: string;
-    salt?: string;
-};
-export type TypedDataField = {
-    name: string;
-    type: string;
-};
-export type TypedData = {
-    domain: TypedDataDomain;
-    types: Record<string, readonly TypedDataField[]>;
-    primaryType: string;
-    message: Record<string, unknown>;
-};
-export type SignTypedDataRequest = [address: string, typedData: TypedData];
-export type SignTypedDataResponse = `0x${string}`;
-export type Call = {
-    to?: string;
-    value?: string;
-    data?: string;
-};
-export type TransactionArgs = Call & {
-    chainId?: string;
-};
-export type SendTransactionRequest = [TransactionArgs];
-export type SendTransactionResponse = `0x${string}`;
-export type SendCallsRequest = [
-    {
-        calls: readonly Call[];
-        chainId?: string;
-        capabilities?: Record<string, unknown>;
-    }
-];
-export type SendCallsResponse = {
-    id: string;
-};
-export type RestoreRequest = [];
-export type RestoreResponse = {
-    jwt: string;
-    user: FlowUser;
-    credential: FlowCredential;
-    address: `0x${string}`;
-};
-export type SignOutRequest = [];
-export type SignOutResponse = {
-    ok: true;
-};
-export type MethodParams = {
-    [METHODS.connect]: ConnectRequest;
-    [METHODS.signMessage]: SignMessageRequest;
-    [METHODS.signTypedData]: SignTypedDataRequest;
-    [METHODS.sendTransaction]: SendTransactionRequest;
-    [METHODS.sendCalls]: SendCallsRequest;
-    [METHODS.restore]: RestoreRequest;
-    [METHODS.signOut]: SignOutRequest;
-};
-export type MethodResult = {
-    [METHODS.connect]: ConnectResponse;
-    [METHODS.signMessage]: SignMessageResponse;
-    [METHODS.signTypedData]: SignTypedDataResponse;
-    [METHODS.sendTransaction]: SendTransactionResponse;
-    [METHODS.sendCalls]: SendCallsResponse;
-    [METHODS.restore]: RestoreResponse;
-    [METHODS.signOut]: SignOutResponse;
-};

package/dist/sdk/client/protocol.js

@@ -1,9 +0,0 @@
-export const METHODS = {
-    connect: "wallet_connect",
-    signMessage: "personal_sign",
-    signTypedData: "eth_signTypedData",
-    sendTransaction: "eth_sendTransaction",
-    sendCalls: "wallet_sendCalls",
-    restore: "wallet_restore",
-    signOut: "wallet_signout",
-};

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

@@ -1,35 +0,0 @@
-import type { Chain } from "viem";
-import type { FlowCredential, FlowUser } from "../types";
-export type { FlowUser, FlowCredential };
-export type Address = `0x${string}`;
-export type AccessKeyOptions = {
-    expiry?: number;
-    strict?: boolean;
-};
-export type CreateFlowOptions = {
-    host?: string;
-    rpId?: string;
-    chains?: readonly Chain[];
-    accessKey?: boolean | AccessKeyOptions;
-    /**
-     * If true (default), createFlow attempts a silent restore on startup —
-     * if the user has a valid Flow cookie session, state populates without UI.
-     */
-    autoRestore?: boolean;
-};
-export type FlowState = {
-    user: FlowUser | null;
-    jwt: string | null;
-    credential: FlowCredential | null;
-    address: Address | null;
-};
-export type LoginOptions = {
-    mode?: "iframe" | "popup";
-    signUp?: boolean;
-};
-export type Session = {
-    user: FlowUser;
-    jwt: string;
-    credential: FlowCredential;
-    address: Address;
-};

package/dist/sdk/types.d.ts

@@ -1,32 +0,0 @@
-export type FlowUser = {
-    id: string;
-    username: string;
-};
-export type FlowCredential = {
-    id: string;
-    publicKey: string;
-};
-export type AuthResponse = {
-    jwt: string;
-    user: FlowUser;
-    credential: FlowCredential;
-};
-export type AuthConfig = {
-    rpId: string;
-    rpName: string;
-};
-export type WebAuthnSignature = {
-    signature: {
-        r: string;
-        s: string;
-    };
-    metadata: {
-        authenticatorData: string;
-        clientDataJSON: string;
-        challengeIndex: number;
-        typeIndex: number;
-    };
-};
-export type AuthResponseWithWebAuthn = AuthResponse & {
-    webauthn?: WebAuthnSignature;
-};