@flow-industries/id 0.19.1 → 0.19.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Flow Industries
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/sdk/client/iframe-host.d.ts

@@ -1,11 +1,18 @@
 import * as Messenger from "../dialog/remote/Messenger";
-import type { Flow } from "../types";
+import type { Flow, ProfileIdentity } from "../types";
 /**
  * Permissions the dialog iframe needs to run WebAuthn passkey ceremonies and
  * copy recovery values. Shared by every Flow iframe host (the dialog host and
  * the profile widget).
  */
 export declare const IFRAME_ALLOW = "publickey-credentials-create; publickey-credentials-get; clipboard-write";
+/**
+ * Geometry for a dialog overlay iframe: a fullscreen layer above everything the
+ * host draws, so the dialog owns the whole viewport and dims the page behind
+ * its own backdrop. Hosts toggle `pointerEvents` on top of this and nothing
+ * else — see the visibility rule on `createProfileButton`.
+ */
+export declare const OVERLAY_STYLE: Partial<CSSStyleDeclaration>;
 /**
  * Creates a Flow dialog iframe element: WebAuthn-permitted, borderless, and
  * `color-scheme: normal` so the iframe itself stays transparent (the rendered
@@ -22,6 +29,12 @@ export declare function makeIframe(src: string): HTMLIFrameElement;
 export declare function bridgeToWindow(target: Window, options?: {
     targetOrigin?: string;
 }): Messenger.Bridge;
+/**
+ * Who the host currently has signed in, in the shape the dialog reads to tell
+ * "this is you" from "this is someone else". Null when signed out, which is a
+ * real answer the dialog renders rather than a missing one it waits for.
+ */
+export declare function hostIdentity(flow: Flow): ProfileIdentity | null;
 /**
  * Answers a widget's request for the host's credential. Every Flow iframe that
  * reads the Flow ID API from a cross-site frame asks for this, because its own

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

@@ -5,6 +5,19 @@ import * as Messenger from "../dialog/remote/Messenger";
  * the profile widget).
  */
 export const IFRAME_ALLOW = "publickey-credentials-create; publickey-credentials-get; clipboard-write";
+/**
+ * Geometry for a dialog overlay iframe: a fullscreen layer above everything the
+ * host draws, so the dialog owns the whole viewport and dims the page behind
+ * its own backdrop. Hosts toggle `pointerEvents` on top of this and nothing
+ * else — see the visibility rule on `createProfileButton`.
+ */
+export const OVERLAY_STYLE = {
+    position: "fixed",
+    inset: "0",
+    width: "100%",
+    height: "100%",
+    zIndex: "2147483647",
+};
 /**
  * Creates a Flow dialog iframe element: WebAuthn-permitted, borderless, and
  * `color-scheme: normal` so the iframe itself stays transparent (the rendered
@@ -32,6 +45,17 @@ export function bridgeToWindow(target, options = {}) {
         waitForReady: true,
     });
 }
+/**
+ * Who the host currently has signed in, in the shape the dialog reads to tell
+ * "this is you" from "this is someone else". Null when signed out, which is a
+ * real answer the dialog renders rather than a missing one it waits for.
+ */
+export function hostIdentity(flow) {
+    const user = flow.getState().user;
+    return user
+        ? { username: user.username, isGuest: user.isGuest === true }
+        : null;
+}
 /**
  * Answers a widget's request for the host's credential. Every Flow iframe that
  * reads the Flow ID API from a cross-site frame asks for this, because its own

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

@@ -1,9 +1,10 @@
 export { defaultIdHost, isLocalHostname } from "../id-host";
-export type { AccessKeyOptions, AdditionalSession, Address, ConnectCapabilities, ConnectResponse, CreateFlowOptions, DialogHost, Flow, FlowCredential, FlowSessionState, FlowState, FlowUser, FlowWidgetHandle, FlowWidgetName, LoginOptions, MethodName, MountFlowWidgetOptions, MountProfileOptions, ProfileButtonHandle, ProfilePosition, Session, } from "../types";
+export type { AccessKeyOptions, AdditionalSession, Address, ConnectCapabilities, ConnectResponse, CreateFlowOptions, DialogHost, Flow, FlowCredential, FlowSessionState, FlowState, FlowUser, FlowWidgetHandle, FlowWidgetName, LoginOptions, MethodName, MountFlowWidgetOptions, MountProfileOptions, OpenProfileOptions, ProfileButtonHandle, ProfilePosition, Session, } from "../types";
 export { createFlow, getFlow, requireFlow, resetFlow } from "./create-flow";
 export { createDialogHost } from "./dialog-host";
 export { createFlowWidget } from "./flow-widget";
 export { METHODS } from "./methods";
+export { closeProfile, openProfile } from "./open-profile";
 export { createProfileButton } from "./profile-button";
 export { createRoomsApi, RoomsRequestError } from "./rooms";
 export { createStaticFlow } from "./static-flow";

package/dist/sdk/client/index.js

@@ -3,6 +3,7 @@ export { createFlow, getFlow, requireFlow, resetFlow } from "./create-flow";
 export { createDialogHost } from "./dialog-host";
 export { createFlowWidget } from "./flow-widget";
 export { METHODS } from "./methods";
+export { closeProfile, openProfile } from "./open-profile";
 export { createProfileButton } from "./profile-button";
 export { createRoomsApi, RoomsRequestError } from "./rooms";
 export { createStaticFlow } from "./static-flow";

package/dist/sdk/client/open-profile.d.ts

@@ -0,0 +1,42 @@
+import type { OpenProfileOptions } from "../types";
+/**
+ * Opens another user's public Flow profile in a fullscreen overlay above the
+ * host page — the read-only view of `@username`: avatar, bio, level and the
+ * month they joined.
+ *
+ * This exists because most Flow surfaces have nowhere to navigate to. The game
+ * draws into a canvas and talk's chat lives in an embedded frame, so following
+ * a link would replace the thing the player is doing; an overlay leaves it
+ * running underneath. The dialog is served by Flow ID itself, so it reads the
+ * profile first-party and inherits the auth dialog's chrome.
+ *
+ * Callers name a **user**, never a route, for the reason `createFlowWidget`
+ * takes a widget name: the dialog's URL space stays an internal detail and an
+ * embedder can't point the frame at an auth route. A profile route is
+ * parameterized, so the SDK validates the name and builds the route itself —
+ * a name that could not belong to a Flow account is refused here rather than
+ * opening the dialog onto a request the server was always going to reject.
+ *
+ * The overlay is created on first use and reused after: opening a second, third
+ * and tenth profile re-points the same iframe, which is what keeps every open
+ * animating and costs no reload. It is safe to call from a click handler on
+ * every name your UI renders.
+ *
+ * Returns whether the profile was opened — `false` for a username that isn't
+ * shaped like a Flow handle, and under SSR, where there is nothing to open.
+ *
+ * ```ts
+ * import { openProfile } from "@flow-industries/id";
+ *
+ * openProfile("alice");
+ * openProfile("bob", { theme: "dark" });
+ * ```
+ */
+export declare function openProfile(username: string, options?: OpenProfileOptions): boolean;
+/**
+ * Closes the profile overlay if one is open. The dialog already closes itself
+ * on its own close button, the backdrop and Escape, so this is for the host
+ * that needs to take the screen back on its own terms — a game resuming play,
+ * a route change in an embedded app. A no-op when nothing is open.
+ */
+export declare function closeProfile(): void;

package/dist/sdk/client/open-profile.js

@@ -0,0 +1,177 @@
+import { resolveIdHost } from "../id-host";
+import { isValidUsername } from "../usernames";
+import { getFlow, requireFlow } from "./create-flow";
+import { answerTokenRequest, bridgeToWindow, hostIdentity, makeIframe, OVERLAY_STYLE, } from "./iframe-host";
+// One overlay per page, kept for the page's lifetime. The alternative — a
+// handle per call site — would put a second fullscreen iframe over the host the
+// moment two parts of an app (a scoreboard and a chat line) both showed a
+// profile, and each would carry its own copy of the dialog.
+let viewer = null;
+function createViewer(options) {
+    const flow = options.flow ?? getFlow() ?? requireFlow();
+    const host = resolveIdHost(options.host ?? flow.host);
+    const hostOrigin = new URL(host).origin;
+    let theme = options.theme ?? "light dark";
+    let frame = null;
+    let bridge = null;
+    // The overlay covers the whole viewport, so it must not accept a click until
+    // the dialog behind it can act on one. `ready` is the child's own handshake:
+    // until it arrives the frame is still loading — or never will, if the host is
+    // unreachable — and a hit-testing overlay would silently eat every click
+    // meant for the page underneath with nothing on screen to explain it.
+    let ready = false;
+    let visible = false;
+    function applyHitTesting() {
+        if (frame)
+            frame.style.pointerEvents = ready && visible ? "auto" : "none";
+    }
+    function mount(username) {
+        const el = makeIframe(`${host}/dialog/`);
+        el.dataset.flowProfileView = "";
+        Object.assign(el.style, OVERLAY_STYLE, { pointerEvents: "none" });
+        // Appended before bridging: `contentWindow` is null until the frame is in
+        // the document, and the bridge is bound to that window.
+        document.body.appendChild(el);
+        frame = el;
+        /* SAFETY: the iframe was just appended, so its contentWindow exists. */
+        const opened = bridgeToWindow(el.contentWindow, {
+            targetOrigin: hostOrigin,
+        });
+        bridge = opened;
+        // The dialog SPA has no deep-link history fallback, so the frame loads at
+        // `/dialog/` and `init` asks it to land on the profile. Sending the route
+        // here rather than as a follow-up message keeps the sign-in root from ever
+        // mounting, even for the frame it takes to navigate away from it.
+        void opened.send("__internal", {
+            type: "init",
+            mode: "iframe",
+            referrer: { title: document.title },
+            theme: { colorScheme: theme },
+            route: `/dialog/u/${username}`,
+        });
+        void opened
+            .waitForReady()
+            .then(() => {
+            ready = true;
+            applyHitTesting();
+        })
+            .catch(() => { });
+        opened.on("close", () => close());
+        opened.on("__internal", (payload) => {
+            // A viewer looking at their own profile can reach the account view from
+            // here, which offers the same sign-in and sign-out the pill's dialog
+            // does. Those run on the host — it owns the session — so dropping them
+            // would leave the buttons doing nothing at all.
+            if (payload.type === "profile-login") {
+                close();
+                void flow
+                    .login(payload.mode === "signup" ? { signUp: true } : { signIn: true })
+                    .catch(() => { });
+            }
+            else if (payload.type === "profile-logout") {
+                close();
+                void flow.logout().catch(() => { });
+            }
+            else if (payload.type === "profile-token-request") {
+                void answerTokenRequest(opened, flow, payload.id);
+            }
+        });
+        return opened;
+    }
+    function open(username) {
+        const mounted = bridge;
+        const live = mounted ?? mount(username);
+        // A frame created just now is already on this profile; an existing one is
+        // re-pointed in place. Tearing it down and rebuilding would reload the
+        // dialog and lose the open animation on every profile after the first.
+        if (mounted)
+            void live.send("__internal", { type: "profile-view", username });
+        // Pushed on every open rather than tracked with a subscription: it is only
+        // read while a profile is on screen, and sending it here means the "this is
+        // you" link is decided from the session as it stands at that moment.
+        void live.send("__internal", {
+            type: "profile-identity",
+            identity: hostIdentity(flow),
+        });
+        visible = true;
+        applyHitTesting();
+        void live.send("__internal", { type: "dialog-shown" });
+    }
+    // Visibility is hit-testing plus a message, and nothing else. The overlay
+    // iframe is NEVER set to `display: none` — that pauses the iframe's
+    // requestAnimationFrame, so motion's engine is asleep when the next open
+    // fires and the animation jumps straight to its end (instant). Keeping it
+    // always-rendered, transparent and click-through while hidden keeps every
+    // open animation reliable, on the second open and the tenth.
+    function close() {
+        if (!frame || !bridge)
+            return;
+        visible = false;
+        applyHitTesting();
+        void bridge.send("__internal", { type: "dialog-hidden" });
+    }
+    function setTheme(next) {
+        if (next === theme)
+            return;
+        theme = next;
+        void bridge?.send("__internal", {
+            type: "set-theme",
+            theme: { colorScheme: next },
+        });
+    }
+    return { open, close, setTheme };
+}
+/**
+ * Opens another user's public Flow profile in a fullscreen overlay above the
+ * host page — the read-only view of `@username`: avatar, bio, level and the
+ * month they joined.
+ *
+ * This exists because most Flow surfaces have nowhere to navigate to. The game
+ * draws into a canvas and talk's chat lives in an embedded frame, so following
+ * a link would replace the thing the player is doing; an overlay leaves it
+ * running underneath. The dialog is served by Flow ID itself, so it reads the
+ * profile first-party and inherits the auth dialog's chrome.
+ *
+ * Callers name a **user**, never a route, for the reason `createFlowWidget`
+ * takes a widget name: the dialog's URL space stays an internal detail and an
+ * embedder can't point the frame at an auth route. A profile route is
+ * parameterized, so the SDK validates the name and builds the route itself —
+ * a name that could not belong to a Flow account is refused here rather than
+ * opening the dialog onto a request the server was always going to reject.
+ *
+ * The overlay is created on first use and reused after: opening a second, third
+ * and tenth profile re-points the same iframe, which is what keeps every open
+ * animating and costs no reload. It is safe to call from a click handler on
+ * every name your UI renders.
+ *
+ * Returns whether the profile was opened — `false` for a username that isn't
+ * shaped like a Flow handle, and under SSR, where there is nothing to open.
+ *
+ * ```ts
+ * import { openProfile } from "@flow-industries/id";
+ *
+ * openProfile("alice");
+ * openProfile("bob", { theme: "dark" });
+ * ```
+ */
+export function openProfile(username, options = {}) {
+    if (!isValidUsername(username))
+        return false;
+    if (!("document" in globalThis))
+        return false;
+    const live = viewer ?? createViewer(options);
+    viewer = live;
+    if (options.theme)
+        live.setTheme(options.theme);
+    live.open(username);
+    return true;
+}
+/**
+ * Closes the profile overlay if one is open. The dialog already closes itself
+ * on its own close button, the backdrop and Escape, so this is for the host
+ * that needs to take the screen back on its own terms — a game resuming play,
+ * a route change in an embedded app. A no-op when nothing is open.
+ */
+export function closeProfile() {
+    viewer?.close();
+}

package/dist/sdk/client/profile-button.js

@@ -1,19 +1,12 @@
 import { resolveIdHost } from "../id-host";
 import { getFlow, requireFlow } from "./create-flow";
-import { answerTokenRequest, bridgeToWindow, makeIframe } from "./iframe-host";
+import { answerTokenRequest, bridgeToWindow, hostIdentity, makeIframe, OVERLAY_STYLE, } from "./iframe-host";
 const POSITION_STYLE = {
     "top-right": { top: "0", right: "0" },
     "top-left": { top: "0", left: "0" },
     "bottom-right": { bottom: "0", right: "0" },
     "bottom-left": { bottom: "0", left: "0" },
 };
-const OVERLAY_STYLE = {
-    position: "fixed",
-    inset: "0",
-    width: "100%",
-    height: "100%",
-    zIndex: "2147483647",
-};
 /**
  * Mounts the universal Flow ID "profile button" — a persistent inline iframe
  * showing the signed-in user's avatar + username (the collapsed pill). Clicking
@@ -77,12 +70,6 @@ export function createProfileButton(options) {
         });
         return bridge;
     }
-    function currentIdentity() {
-        const user = flow.getState().user;
-        return user
-            ? { username: user.username, isGuest: user.isGuest === true }
-            : null;
-    }
     // ----- the persistent pill (stays mounted; sizes to its own content) -----
     const pill = makeFrame();
     let pillWidth = 0;
@@ -143,7 +130,7 @@ export function createProfileButton(options) {
         });
         void dialogBridge.send("__internal", {
             type: "profile-identity",
-            identity: currentIdentity(),
+            identity: hostIdentity(flow),
         });
     }
     // The dialog owns its open/close animation entirely; the host only signals
@@ -170,7 +157,7 @@ export function createProfileButton(options) {
     // skip re-sending an identical identity (e.g. on every silent JWT refresh).
     let lastIdentityKey;
     function pushIdentity() {
-        const identity = currentIdentity();
+        const identity = hostIdentity(flow);
         const key = identity ? `${identity.username}|${identity.isGuest}` : "none";
         if (key === lastIdentityKey)
             return;

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

@@ -1,5 +1,6 @@
-export type { FlowIdProviderProps, FlowWidgetProps, ProfileButtonProps, } from "../types";
+export type { FlowIdProviderProps, FlowWidgetProps, ProfileButtonProps, UseOpenProfileOptions, } from "../types";
 export { FlowWidget } from "./flow-widget";
 export { useFlow, useFlowId, useFlowState, useRoom, useRooms } from "./hooks";
+export { useOpenProfile } from "./open-profile";
 export { ProfileButton } from "./profile-button";
 export { FlowIdProvider } from "./provider";

package/dist/sdk/react/index.js

@@ -1,4 +1,5 @@
 export { FlowWidget } from "./flow-widget";
 export { useFlow, useFlowId, useFlowState, useRoom, useRooms } from "./hooks";
+export { useOpenProfile } from "./open-profile";
 export { ProfileButton } from "./profile-button";
 export { FlowIdProvider } from "./provider";

package/dist/sdk/react/open-profile.d.ts

@@ -0,0 +1,18 @@
+import type { UseOpenProfileOptions } from "../types";
+/**
+ * Returns a callback that opens another user's public Flow profile in the
+ * shared overlay — the React face of `openProfile`, resolving the Flow instance
+ * from a `<FlowIdProvider>` ancestor or the createFlow() singleton so callers
+ * don't thread it through. The callback returns false for a username that isn't
+ * shaped like a Flow handle.
+ *
+ * There is deliberately nothing to clean up on unmount: the overlay belongs to
+ * the page, not to the component that first opened it, so every name in a chat
+ * log or a scoreboard shares one iframe and one dialog.
+ *
+ * ```tsx
+ * const openProfile = useOpenProfile({ theme: "dark" });
+ * return <button onClick={() => openProfile(player.username)}>@{player.username}</button>;
+ * ```
+ */
+export declare function useOpenProfile(options?: UseOpenProfileOptions): (username: string) => boolean;

package/dist/sdk/react/open-profile.js

@@ -0,0 +1,24 @@
+import { useCallback } from "react";
+import { openProfile } from "../client/open-profile";
+import { useFlow } from "./hooks";
+/**
+ * Returns a callback that opens another user's public Flow profile in the
+ * shared overlay — the React face of `openProfile`, resolving the Flow instance
+ * from a `<FlowIdProvider>` ancestor or the createFlow() singleton so callers
+ * don't thread it through. The callback returns false for a username that isn't
+ * shaped like a Flow handle.
+ *
+ * There is deliberately nothing to clean up on unmount: the overlay belongs to
+ * the page, not to the component that first opened it, so every name in a chat
+ * log or a scoreboard shares one iframe and one dialog.
+ *
+ * ```tsx
+ * const openProfile = useOpenProfile({ theme: "dark" });
+ * return <button onClick={() => openProfile(player.username)}>@{player.username}</button>;
+ * ```
+ */
+export function useOpenProfile(options = {}) {
+    const flow = useFlow();
+    const { host, theme } = options;
+    return useCallback((username) => openProfile(username, { flow, host, theme }), [flow, host, theme]);
+}

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

@@ -25,7 +25,34 @@ export interface SessionUser {
     isGuest?: boolean;
     role?: string | null;
     image?: string | null;
+    bio?: string | null;
 }
+/** Why a submitted bio was refused: it carried control or bidi characters, or
+ *  it was longer than `MAX_BIO_LENGTH` once normalized. */
+export type BioRejection = "unsafe_characters" | "too_long";
+/**
+ * The result of normalizing a submitted bio. On success `bio` is the value to
+ * store — `null` when the input normalized to nothing, which clears the bio.
+ */
+export type BioNormalization = {
+    ok: true;
+    bio: string | null;
+} | {
+    ok: false;
+    reason: BioRejection;
+};
+/** Why a bio write was refused: the caller is a guest, or the text itself was
+ *  refused. A bio belongs to a full account, the same rule the avatar upload
+ *  applies. */
+export type BioWriteRefusal = BioRejection | "guest";
+/** The result of a bio write. `bio: null` means the bio was cleared. */
+export type BioWriteResult = {
+    ok: true;
+    bio: string | null;
+} | {
+    ok: false;
+    reason: BioWriteRefusal;
+};
 /**
  * A session minted for one of the ADDITIONAL audiences a login requested
  * (AUTH-39): its own refresh-token lineage and access JWT, both bound to

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

@@ -36,7 +36,7 @@ export type EquipRegion = "whole_head" | "hat" | "hair" | "face" | "glasses" | "
  * makes the same mistake a typecheck error — which is the whole point of
  * mirroring the names into one constant. AUTH-210 is what happens without it:
  * the catalog was written from a nine-region proposal in
- * `docs/internal/cosmetics/bodygroups.md` section 6, the fifteen-region cut
+ * the GAME page "design: cosmetic bodygroups" section 6, the fifteen-region cut
  * that actually shipped shared not one name with it, and every cosmetic
  * silently suppressed nothing.
  */

package/dist/sdk/types/cosmetics.js

@@ -27,7 +27,7 @@
  * makes the same mistake a typecheck error — which is the whole point of
  * mirroring the names into one constant. AUTH-210 is what happens without it:
  * the catalog was written from a nine-region proposal in
- * `docs/internal/cosmetics/bodygroups.md` section 6, the fifteen-region cut
+ * the GAME page "design: cosmetic bodygroups" section 6, the fifteen-region cut
  * that actually shipped shared not one name with it, and every cosmetic
  * silently suppressed nothing.
  */

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

@@ -52,12 +52,13 @@ export type DialogCustomLabels = {
 };
 /**
  * The profile fields the widget renders, read from `/api/me` (the cookie
- * session's `session.user`). `image`/`createdAt` are not on the SDK's
+ * session's `session.user`). `image`/`bio`/`createdAt` are not on the SDK's
  * `FlowUser`, so they only come from this authenticated fetch.
  */
 export type ProfileData = {
     username: string;
     image?: string | null;
+    bio?: string | null;
     createdAt?: string;
     isGuest?: boolean;
 };

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

@@ -9,8 +9,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" | "ceremony_failed" | "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.passkey.added" | "auth.passkey.add_failed" | "auth.restore.succeeded" | "auth.restore.failed" | "auth.restore.no_session" | "auth.refresh.succeeded" | "auth.refresh.failed" | "auth.refresh.reuse" | "auth.refresh.grace" | "auth.jwt.verified" | "auth.jwt.rejected" | "auth.signout" | "auth.session.revoked" | "auth.session.revoked_all" | "auth.audience.rejected" | "auth.audience.minted" | "auth.guest.created" | "auth.guest.restored" | "auth.guest.upgraded" | "auth.guest.failed" | "auth.role.granted" | "auth.role.revoked" | "room.restriction.issued" | "room.restriction.lifted" | "auth.funnel.mode_selected" | "auth.funnel.email_entered" | "auth.funnel.ceremony_started" | "auth.funnel.ceremony_failed" | "auth.funnel.done_shown" | "room_event.activated" | "room_event.completed" | "room_event.reminder_dispatched" | "room_event.reminder_failed";
-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_epoch_stale" | "refresh_user_epoch_stale" | "refresh_reuse_detected" | "guest_rate_limited" | "guest_global_limit" | "guest_username_exhausted" | "guest_session" | "passkey_exists" | "already_upgraded" | "malformed_token" | "unknown_key" | "verification_failed" | "webauthn_not_allowed" | "webauthn_security" | "webauthn_invalid_state" | "webauthn_not_supported" | "webauthn_constraint" | "webauthn_aborted" | "webauthn_unknown" | "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.bio.update.succeeded" | "auth.bio.update.failed" | "auth.profile.view.failed" | "auth.profile.view.uncapped" | "auth.challenge.issued" | "auth.signin.succeeded" | "auth.signin.failed" | "auth.passkey.added" | "auth.passkey.add_failed" | "auth.restore.succeeded" | "auth.restore.failed" | "auth.restore.no_session" | "auth.refresh.succeeded" | "auth.refresh.failed" | "auth.refresh.reuse" | "auth.refresh.grace" | "auth.jwt.verified" | "auth.jwt.rejected" | "auth.signout" | "auth.session.revoked" | "auth.session.revoked_all" | "auth.audience.rejected" | "auth.audience.minted" | "auth.guest.created" | "auth.guest.restored" | "auth.guest.upgraded" | "auth.guest.failed" | "auth.role.granted" | "auth.role.revoked" | "room.restriction.issued" | "room.restriction.lifted" | "auth.funnel.mode_selected" | "auth.funnel.email_entered" | "auth.funnel.ceremony_started" | "auth.funnel.ceremony_failed" | "auth.funnel.done_shown" | "room_event.activated" | "room_event.completed" | "room_event.reminder_dispatched" | "room_event.reminder_failed";
+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" | "bio_forbidden" | "bio_invalid" | "bio_too_long" | "profile_rate_limited" | "profile_ip_missing" | "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_epoch_stale" | "refresh_user_epoch_stale" | "refresh_reuse_detected" | "guest_rate_limited" | "guest_global_limit" | "guest_username_exhausted" | "guest_session" | "passkey_exists" | "already_upgraded" | "malformed_token" | "unknown_key" | "verification_failed" | "webauthn_not_allowed" | "webauthn_security" | "webauthn_invalid_state" | "webauthn_not_supported" | "webauthn_constraint" | "webauthn_aborted" | "webauthn_unknown" | "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

@@ -1,4 +1,4 @@
-export type { AccountSession, AccountSessionsResponse, AdditionalSession, AuthConfig, AuthResponse, AuthResponseWithWebAuthn, FlowCredential, FlowUser, PasskeyPluginOptions, RevokeAllSessionsResponse, RevokeSessionResponse, SecurityActivityEntry, SecurityActivityResponse, SessionUser, VerifiedFlowJWT, VerifyOptions, WebAuthnSignature, } from "./auth";
+export type { AccountSession, AccountSessionsResponse, AdditionalSession, AuthConfig, AuthResponse, AuthResponseWithWebAuthn, BioNormalization, BioRejection, BioWriteRefusal, BioWriteResult, FlowCredential, FlowUser, PasskeyPluginOptions, RevokeAllSessionsResponse, RevokeSessionResponse, SecurityActivityEntry, SecurityActivityResponse, SessionUser, VerifiedFlowJWT, VerifyOptions, WebAuthnSignature, } from "./auth";
 export type { BodyRegion, CosmeticItem, CosmeticMaterial, CosmeticPaint, CosmeticSlot, EquipConflict, EquippedCosmetic, EquippedCosmetics, EquipRegion, PaintSlot, SettingsConflict, } from "./cosmetics";
 export { BODY_REGIONS, COSMETIC_MATERIALS } from "./cosmetics";
 export type { BoundaryError, DialogCustomFeatures, DialogCustomLabels, DialogError, DialogReferrer, DialogState, Loadable, ProfileData, ProfileIdentity, } from "./dialog";
@@ -10,7 +10,7 @@ export type { Call, ConnectCapabilities, ConnectRequest, ConnectResponse, GuestR
 export { getConnectCapabilities, isPersonalSignParams, isSendCallsParams, isSendTransactionParams, } from "./protocol";
 export type { CreateRoomEventInput, RoomEventArchive, RoomEventAttendance, RoomEventFrequency, RoomEventInstance, RoomEventInterest, RoomEventInterestState, RoomEventList, RoomEventOccurrence, RoomEventRecurrence, RoomEventRoomRef, RoomEventRun, RoomEventSeries, RoomEventStatus, SetInterestInput, UpdateRoomEventInput, } from "./room-events";
 export type { CreateRoomInput, GlobalRole, ModerationSubject, MyRooms, PlayerPositionReport, RoleChangeVerdict, RoomCapabilities, RoomCapability, RoomChannel, RoomDetail, RoomList, RoomMemberEntry, RoomMembers, RoomOccupancy, RoomOwner, RoomPlayerPosition, RoomPresenceEntry, RoomPresenceSnapshot, RoomRestrictionKind, RoomRole, RoomSummary, RoomSurfaceSettings, RoomsApi, RoomVisibility, StaffEntry, UpdateRoomInput, VerifyRoomContext, Viewer, VoiceDecisionReason, VoiceDecisionSubject, VoiceRoomDecision, } from "./rooms";
-export type { AccessKeyOptions, AccessKeyPreparation, Address, ColorScheme, CreateDialogHostOptions, CreateFlowOptions, DialogHost, DialogOpenOptions, FinalizeAccessKeyParams, Flow, FlowConnectorParameters, FlowCookieNames, FlowIdProviderProps, FlowSessionState, FlowState, FlowWidgetHandle, FlowWidgetName, FlowWidgetProps, Listener, LoginOptions, MountFlowWidgetOptions, 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 { AccessKeyOptions, AccessKeyPreparation, Address, ColorScheme, CreateDialogHostOptions, CreateFlowOptions, DialogHost, DialogOpenOptions, FinalizeAccessKeyParams, Flow, FlowConnectorParameters, FlowCookieNames, FlowIdProviderProps, FlowSessionState, FlowState, FlowWidgetHandle, FlowWidgetName, FlowWidgetProps, Listener, LoginOptions, MountFlowWidgetOptions, MountProfileOptions, OpenProfileOptions, PrepareArgsWithAuth, PrepareTransactionRequestPhase, ProfileButtonHandle, ProfileButtonProps, ProfilePosition, ResolveAccountParams, ResolvedAccessKeyOptions, RootCredential, RunLoginParams, RunLoginResult, SendCallsArgs, SendTransactionArgs, Session, SigningContext, SignMessageArgs, SignTypedDataArgs, Store, StoredAccessKey, UseOpenProfileOptions, WagmiConnectCapabilities, WagmiConnectParams, } from "./sdk";
 export type { GracefulShutdownCleanup, GracefulShutdownOptions, GracefulShutdownServer, GracefulShutdownSignal, ResolvedFlowSession, ResolveSessionOptions, SessionRouteOptions, SessionRouteResponse, SessionRouteSession, } from "./server";
 export type { CoinAsset, IdentifiedTx, TxApprove, TxConvert, TxSend, TxSwap, } from "./tx";
-export type { ActionDayContext, ActionEventKind, ActionSessionState, ActionTransitionKind, ActiveActionResponse, LevelProgress, PublicProfile, XpGrantResult, XpRecentGrant, XpSummary, } from "./xp";
+export type { ActionDayContext, ActionEventKind, ActionSessionState, ActionTransitionKind, ActiveActionResponse, LevelProgress, PublicProfile, PublicProfileRefusal, PublicProfileResult, PublicProfileSignal, PublicUserProfile, XpGrantResult, XpRecentGrant, XpSummary, } from "./xp";

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

@@ -84,6 +84,9 @@ export type Schema = [
             height: number;
         } | {
             type: "profile-expand";
+        } | {
+            type: "profile-view";
+            username: string;
         } | {
             type: "profile-identity";
             identity: {

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

@@ -229,6 +229,32 @@ export type ProfileButtonHandle = {
     /** Tears down the iframe, listeners, and any auto-created container. */
     destroy: () => void;
 };
+export type OpenProfileOptions = {
+    /**
+     * The Flow ID origin serving the overlay (e.g. https://id.flow.industries).
+     * Defaults to the resolved Flow instance's `host`, then the SDK default.
+     * Read once, when the overlay is first created — every later open reuses it.
+     */
+    host?: string;
+    /**
+     * Color scheme for the dialog chrome. Set this to match the host (the dark
+     * game UI passes "dark"). Applied on every open, so a host with a theme
+     * toggle needs no separate call. Defaults to "light dark" (follows the OS).
+     */
+    theme?: ColorScheme;
+    /**
+     * Explicit Flow instance, used to answer the dialog's token requests and to
+     * tell it who is looking. Defaults to the createFlow() singleton, and like
+     * `host` is read once, when the overlay is first created.
+     */
+    flow?: Flow;
+};
+export type UseOpenProfileOptions = {
+    /** Override the Flow ID origin; defaults to the resolved Flow's `host`. */
+    host?: string;
+    /** Color scheme for the dialog chrome; defaults to "light dark" (the OS). */
+    theme?: ColorScheme;
+};
 /** The inline Flow ID widgets an embedder can mount alongside its own UI. */
 export type FlowWidgetName = "xp" | "action-timer";
 export type MountFlowWidgetOptions = {

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

@@ -71,3 +71,43 @@ export interface PublicProfile {
     tier: number;
     level: number;
 }
+/** Everything `GET /api/users/:username` shows about a user: the identity
+ * fields anyone may see plus the same XP standing the nametag carries.
+ * `flowScore` is public by decision, so a future leaderboard row can link this
+ * endpoint rather than adding a second one. Deliberately no email, wallet
+ * address, role, session state or `updatedAt` — a change here is a change to
+ * what Flow publishes about a person. camelCase, unlike the snake_case
+ * `PublicProfile` nested in the game-server verify payload: this one is read by
+ * web clients, where every other Flow payload is camelCase. */
+export interface PublicUserProfile {
+    username: string;
+    image: string | null;
+    bio: string | null;
+    level: number;
+    tier: number;
+    flowScore: number;
+    /** UTC calendar date the account was created, `YYYY-MM-DD`, rendered as
+     * "Joined ...". Deliberately not a full timestamp: no consumer shows the
+     * clock time, and a public by-name payload should carry no more of one than
+     * it displays. */
+    createdAt: string;
+}
+/** Why a public profile read was refused. `not_found` covers both an unknown
+ * username and a guest row — a guest is a placeholder, not a person, and the
+ * two are deliberately indistinguishable to the caller. */
+export type PublicProfileRefusal = "invalid_username" | "not_found" | "rate_limited";
+/** Whether a read did something its route should emit an event for, resolved
+ * against the caller's quota window so a flood produces one row rather than
+ * one per request. `cap_crossed` marks the request that spent the last slot;
+ * `ip_missing` marks the first header-less caller in a window, which is a
+ * deployment fault worth seeing and is served uncapped. */
+export type PublicProfileSignal = "none" | "cap_crossed" | "ip_missing";
+export type PublicProfileResult = {
+    ok: true;
+    profile: PublicUserProfile;
+    signal: PublicProfileSignal;
+} | {
+    ok: false;
+    reason: PublicProfileRefusal;
+    signal: PublicProfileSignal;
+};

package/dist/sdk/usernames.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Shared adjective/noun wordlists and the playful `adjective_noun####`
+ * generator. Single source of truth for both the server (collision-safe guest
+ * account creation) and the dialog (the sign-up username placeholder), so the
+ * two can never drift. The wordlists are chosen so the longest combination
+ * stays within the 20-char username limit.
+ */
+export declare const funnyAdjectives: string[];
+export declare const funnyNouns: string[];
+/** Single source of truth for the username constraints, shared by the
+ *  generator and the server-side validators (register zod, availability check). */
+export declare const MAX_USERNAME_LENGTH = 20;
+export declare const USERNAME_REGEX: RegExp;
+/**
+ * Whether a string can address a Flow account at all — the constraints above
+ * applied together. This is the check to spend before a lookup, because it is
+ * the same one `/api/users/:username` applies before it touches the database:
+ * anything it rejects can only ever come back as a refusal, so a caller that
+ * runs it first never opens a view onto a guaranteed 400.
+ */
+export declare function isValidUsername(name: string): boolean;
+/**
+ * A playful `adjective_noun####` handle. Matches `USERNAME_REGEX` and is capped
+ * to `MAX_USERNAME_LENGTH`. NOT collision-checked — callers needing uniqueness
+ * (guest creation) retry against the username unique index.
+ */
+export declare function randomGuestUsername(): string;

package/dist/sdk/usernames.js

@@ -0,0 +1,101 @@
+/**
+ * Shared adjective/noun wordlists and the playful `adjective_noun####`
+ * generator. Single source of truth for both the server (collision-safe guest
+ * account creation) and the dialog (the sign-up username placeholder), so the
+ * two can never drift. The wordlists are chosen so the longest combination
+ * stays within the 20-char username limit.
+ */
+export const funnyAdjectives = [
+    "cool",
+    "epic",
+    "lazy",
+    "sneaky",
+    "brave",
+    "chill",
+    "wild",
+    "tiny",
+    "mega",
+    "turbo",
+    "hyper",
+    "cozy",
+    "swift",
+    "bold",
+    "dark",
+    "lost",
+    "lucky",
+    "dizzy",
+    "fuzzy",
+    "shiny",
+    "sleepy",
+    "spicy",
+    "crispy",
+    "flowy",
+    "donkey",
+];
+export const funnyNouns = [
+    "goku",
+    "naruto",
+    "pikachu",
+    "saitama",
+    "kirby",
+    "zelda",
+    "mario",
+    "sonic",
+    "yoshi",
+    "toad",
+    "kakashi",
+    "luffy",
+    "gojo",
+    "todoroki",
+    "midoriya",
+    "vegeta",
+    "jotaro",
+    "tanjiro",
+    "link",
+    "kratos",
+    "sora",
+    "roxas",
+    "cloud",
+    "sephiroth",
+    "megaman",
+    "waluigi",
+    "bowser",
+    "ganon",
+    "kong",
+    "king",
+];
+/** Single source of truth for the username constraints, shared by the
+ *  generator and the server-side validators (register zod, availability check). */
+export const MAX_USERNAME_LENGTH = 20;
+export const USERNAME_REGEX = /^[a-z0-9_]+$/;
+/**
+ * Whether a string can address a Flow account at all — the constraints above
+ * applied together. This is the check to spend before a lookup, because it is
+ * the same one `/api/users/:username` applies before it touches the database:
+ * anything it rejects can only ever come back as a refusal, so a caller that
+ * runs it first never opens a view onto a guaranteed 400.
+ */
+export function isValidUsername(name) {
+    // Typed as a string but reached from untyped JavaScript: the SDK hands this
+    // whatever a chat payload or a nametag produced, where a missing name is an
+    // ordinary outcome. Answering "no" is the contract; throwing is not.
+    //
+    // Established structurally, and deliberately BEFORE the charset test, because
+    // coercion would answer yes: `String(null)` is "null" and `String(undefined)`
+    // is "undefined", both of which the charset accepts as perfectly good
+    // usernames. A missing name would open a stranger's profile.
+    if (Object.prototype.toString.call(name) !== "[object String]")
+        return false;
+    return name.length <= MAX_USERNAME_LENGTH && USERNAME_REGEX.test(name);
+}
+/**
+ * A playful `adjective_noun####` handle. Matches `USERNAME_REGEX` and is capped
+ * to `MAX_USERNAME_LENGTH`. NOT collision-checked — callers needing uniqueness
+ * (guest creation) retry against the username unique index.
+ */
+export function randomGuestUsername() {
+    const adj = funnyAdjectives[Math.floor(Math.random() * funnyAdjectives.length)];
+    const noun = funnyNouns[Math.floor(Math.random() * funnyNouns.length)];
+    const num = Math.floor(Math.random() * 9999) + 1;
+    return `${adj}_${noun}${num}`.slice(0, MAX_USERNAME_LENGTH);
+}

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@flow-industries/id",
-  "version": "0.19.1",
+  "version": "0.19.3",
+  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/flow-industries/auth.git"