@flow-industries/id 0.2.0

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

@@ -0,0 +1,114 @@
+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 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: Address;
+};
+export type SignOutRequest = [];
+export type SignOutResponse = {
+    ok: true;
+};
+export type MethodParams = {
+    wallet_connect: ConnectRequest;
+    personal_sign: SignMessageRequest;
+    eth_signTypedData: SignTypedDataRequest;
+    eth_sendTransaction: SendTransactionRequest;
+    wallet_sendCalls: SendCallsRequest;
+    wallet_restore: RestoreRequest;
+    wallet_signout: SignOutRequest;
+};
+export type MethodResult = {
+    wallet_connect: ConnectResponse;
+    personal_sign: SignMessageResponse;
+    eth_signTypedData: SignTypedDataResponse;
+    eth_sendTransaction: SendTransactionResponse;
+    wallet_sendCalls: SendCallsResponse;
+    wallet_restore: RestoreResponse;
+    wallet_signout: SignOutResponse;
+};
+export type RpcRequest = {
+    id: string | number;
+    method: string;
+    params?: readonly unknown[];
+    jsonrpc?: string;
+    [key: string]: unknown;
+};
+export type SendTransactionParams = {
+    to?: string;
+    value?: string;
+    data?: string;
+    chainId?: string;
+};
+export type SendCallsParams = {
+    calls: readonly {
+        to?: string;
+        value?: string;
+        data?: string;
+    }[];
+    chainId?: string;
+    capabilities?: Record<string, unknown>;
+};
+export declare function isPersonalSignParams(params: readonly unknown[] | undefined): params is readonly [string, string];
+export declare function isSendTransactionParams(params: readonly unknown[] | undefined): params is readonly [SendTransactionParams];
+export declare function isSendCallsParams(params: readonly unknown[] | undefined): params is readonly [SendCallsParams];

package/dist/sdk/types/protocol.js

@@ -0,0 +1,17 @@
+export function isPersonalSignParams(params) {
+    if (!params || params.length < 2)
+        return false;
+    return typeof params[0] === "string" && typeof params[1] === "string";
+}
+export function isSendTransactionParams(params) {
+    if (!params || params.length < 1)
+        return false;
+    const p = params[0];
+    return p != null && typeof p === "object";
+}
+export function isSendCallsParams(params) {
+    if (!params || params.length < 1)
+        return false;
+    const p = params[0];
+    return p != null && typeof p === "object" && Array.isArray(p.calls);
+}

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

@@ -0,0 +1,166 @@
+import type { Chain, Hex, 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}`;
+export type CreateDialogHostOptions = {
+    host: string;
+    container?: HTMLElement;
+};
+export type AccessKeyOptions = {
+    expiry?: number;
+    strict?: boolean;
+};
+export type ResolvedAccessKeyOptions = {
+    expiry: number;
+    strict: boolean;
+};
+export type StoredAccessKey = {
+    privateKey: unknown;
+    publicKey: unknown;
+    keyAuthorization: unknown;
+};
+export type AccessKeyPreparation = {
+    keyPair: {
+        privateKey: unknown;
+        publicKey: unknown;
+    };
+    keyAuthUnsigned: unknown;
+    accessKeyHash: string;
+};
+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;
+};
+export type RootCredential = {
+    credential: FlowCredential;
+    address: Address;
+};
+export type SigningContext = {
+    getState(): FlowState;
+    getChain(chainId?: number): Chain | undefined;
+    getTransport(chainId: number): Transport | undefined;
+    rpId?: string;
+    strict?: boolean;
+};
+export type SignMessageArgs = {
+    message: string;
+    chainId?: number;
+};
+export type SignTypedDataArgs = Omit<SignTypedDataParameters, "account"> & {
+    chainId?: number;
+};
+export type SendTransactionArgs = Omit<SendTransactionParameters, "account" | "chain"> & {
+    chainId?: number;
+};
+export type SendCallsArgs = Omit<SendCallsParameters, "account" | "chain"> & {
+    chainId?: number;
+};
+export type Listener<T> = (state: T) => void;
+export type Store<T> = {
+    getSnapshot(): T;
+    setState(partial: Partial<T>): void;
+    subscribe(listener: Listener<T>): () => void;
+};
+export type DialogOpenOptions = {
+    mode?: "iframe" | "popup";
+    theme?: {
+        colorScheme?: string;
+    };
+    referrer?: {
+        title: string;
+        icon?: string;
+    };
+};
+export type DialogHost = {
+    open: (options?: DialogOpenOptions) => void;
+    close: () => void;
+    destroy: () => void;
+    request: <T = unknown>(method: string, params?: readonly unknown[]) => Promise<T>;
+    requestSilent: <T = unknown>(method: string, params?: readonly unknown[]) => Promise<T>;
+    messenger: import("./messenger").Messenger;
+};
+export type Flow = {
+    readonly user: FlowState["user"];
+    readonly jwt: FlowState["jwt"];
+    readonly credential: FlowState["credential"];
+    readonly address: Address | null;
+    readonly isAuthenticated: boolean;
+    login(options?: LoginOptions): Promise<Session>;
+    logout(): Promise<void>;
+    restore(): Promise<boolean>;
+    refreshJwt(): Promise<boolean>;
+    signMessage(args: SignMessageArgs): Promise<Hex>;
+    signTypedData(args: SignTypedDataArgs): Promise<Hex>;
+    sendTransaction(args: SendTransactionArgs): Promise<Hex>;
+    sendCalls(args: SendCallsArgs): Promise<{
+        id: string;
+    }>;
+    walletClient(args?: {
+        chainId?: number;
+    }): Promise<WalletClient>;
+    subscribe(listener: Listener<FlowState>): () => void;
+    getState(): FlowState;
+    dialog: DialogHost;
+};
+export type FlowConnectorParameters = Omit<CreateFlowOptions, "chains"> & {
+    /**
+     * Pass an existing Flow instance so wagmi shares state with direct SDK usage.
+     * If omitted, the connector creates its own internal Flow (separate state).
+     */
+    flow?: Flow;
+};
+export type FlowIdProviderProps = {
+    /**
+     * Explicit Flow instance to scope to descendants. Optional — if omitted,
+     * descendants resolve via the singleton set by `createFlow()`.
+     */
+    flow?: Flow;
+    children: ReactNode;
+};
+export type RunLoginParams = {
+    dialog: DialogHost;
+    store: Store<FlowState>;
+    options?: LoginOptions;
+    extraCapabilities?: ConnectCapabilities;
+};
+export type RunLoginResult = {
+    session: Session;
+    webauthn: ConnectResponse["webauthn"];
+};
+export type FinalizeAccessKeyParams = {
+    address: Address;
+    credential: FlowCredential;
+    webauthn: WebAuthnSignature;
+    preparation: AccessKeyPreparation;
+};
+export type ResolveAccountParams = {
+    credential: FlowCredential;
+    address: Address;
+    rpId?: string;
+    strict?: boolean;
+};

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

@@ -0,0 +1,35 @@
+export type CoinAsset = {
+    address: string | null;
+    direction: "incoming" | "outgoing";
+    name?: string;
+    symbol?: string;
+    type: "erc20" | null;
+    value: bigint;
+    decimals?: number | null;
+    fiat?: {
+        value: number;
+    };
+};
+export type TxApprove = {
+    type: "approve";
+    tokenAddress: string;
+    spender: string;
+    amount: bigint;
+};
+export type TxSwap = {
+    type: "swap";
+    assetIn: CoinAsset;
+    assetOut: CoinAsset;
+};
+export type TxSend = {
+    type: "send";
+    asset: CoinAsset;
+    to?: string;
+};
+export type TxConvert = {
+    type: "convert";
+    assetIn: CoinAsset;
+    assetOut: CoinAsset;
+    direction: "wrap" | "unwrap";
+};
+export type IdentifiedTx = TxApprove | TxSwap | TxSend | TxConvert;

package/dist/sdk/types.d.ts

@@ -0,0 +1,32 @@
+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;
+};

package/dist/sdk/verify.d.ts

@@ -0,0 +1,15 @@
+import type { VerifiedFlowJWT, VerifyOptions } from "./types";
+export type { VerifiedFlowJWT, VerifyOptions } from "./types";
+/**
+ * Server-side helper for verifying a Flow JWT. Used by relying-party backends
+ * (e.g., flow.game's game server) to authenticate API requests where the
+ * client has presented `Authorization: Bearer <jwt>`.
+ *
+ * Fetches the issuer's JWKS once per process and caches it (the keys rotate
+ * but rarely; jose handles refresh transparently). Verifies signature,
+ * issuer, audience, and expiry; rejects tokens missing `sub`.
+ *
+ * `audience` MUST match the calling app's origin — this is what prevents
+ * a token issued for `flow.talk` from being replayed against `flow.game`.
+ */
+export declare function verifyFlowJWT(token: string, opts: VerifyOptions): Promise<VerifiedFlowJWT>;

package/dist/sdk/verify.js

@@ -0,0 +1,30 @@
+import { createRemoteJWKSet, jwtVerify } from "jose";
+const jwksCache = new Map();
+const DEFAULT_ISSUER_URL = "https://id.flow.industries";
+/**
+ * Server-side helper for verifying a Flow JWT. Used by relying-party backends
+ * (e.g., flow.game's game server) to authenticate API requests where the
+ * client has presented `Authorization: Bearer <jwt>`.
+ *
+ * Fetches the issuer's JWKS once per process and caches it (the keys rotate
+ * but rarely; jose handles refresh transparently). Verifies signature,
+ * issuer, audience, and expiry; rejects tokens missing `sub`.
+ *
+ * `audience` MUST match the calling app's origin — this is what prevents
+ * a token issued for `flow.talk` from being replayed against `flow.game`.
+ */
+export async function verifyFlowJWT(token, opts) {
+    const issuerUrl = opts.issuerUrl ?? DEFAULT_ISSUER_URL;
+    let jwks = jwksCache.get(issuerUrl);
+    if (!jwks) {
+        jwks = createRemoteJWKSet(new URL(`${issuerUrl}/api/auth/jwks`));
+        jwksCache.set(issuerUrl, jwks);
+    }
+    const { payload } = await jwtVerify(token, jwks, {
+        issuer: issuerUrl,
+        audience: opts.audience,
+    });
+    if (!payload.sub)
+        throw new Error("JWT missing sub");
+    return payload;
+}

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

@@ -0,0 +1,25 @@
+import type { FlowConnectorParameters } from "../types";
+/**
+ * Wagmi connector adapter for Flow. Drop into your wagmi config with
+ * `connectors: [flowConnector()]` — no arguments needed in the common case.
+ *
+ * Resolution order for the underlying Flow instance:
+ *  1. `parameters.flow` (explicit override — useful for tests)
+ *  2. The Flow singleton set by a prior `createFlow()` call
+ *  3. Lazily created on first connector use (also sets the singleton)
+ *
+ * This means wagmi-only apps get a working Flow without ever calling
+ * `createFlow`, and apps mixing wagmi + direct SDK calls automatically
+ * share state because they all resolve to the same singleton.
+ *
+ * The `setup()` method subscribes to the Flow store and emits wagmi
+ * `connect`/`disconnect` events whenever the address changes — that's how
+ * wagmi state stays in sync when login/logout happens via the SDK rather
+ * than through wagmi's own `connect()`.
+ */
+export declare function flowConnector(parameters?: FlowConnectorParameters): import("@wagmi/core").CreateConnectorFn<{
+    request: (...args: unknown[]) => Promise<unknown>;
+}, Record<string, unknown>, Record<string, unknown>>;
+export declare namespace flowConnector {
+    var type: "flow";
+}

package/dist/sdk/wagmi/index.js

@@ -0,0 +1,139 @@
+import { createConnector } from "@wagmi/core";
+import { getAddress, SwitchChainError } from "viem";
+import { createFlow, getFlow as getSingletonFlow } from "../client/create-flow";
+flowConnector.type = "flow";
+/**
+ * Wagmi connector adapter for Flow. Drop into your wagmi config with
+ * `connectors: [flowConnector()]` — no arguments needed in the common case.
+ *
+ * Resolution order for the underlying Flow instance:
+ *  1. `parameters.flow` (explicit override — useful for tests)
+ *  2. The Flow singleton set by a prior `createFlow()` call
+ *  3. Lazily created on first connector use (also sets the singleton)
+ *
+ * This means wagmi-only apps get a working Flow without ever calling
+ * `createFlow`, and apps mixing wagmi + direct SDK calls automatically
+ * share state because they all resolve to the same singleton.
+ *
+ * The `setup()` method subscribes to the Flow store and emits wagmi
+ * `connect`/`disconnect` events whenever the address changes — that's how
+ * wagmi state stays in sync when login/logout happens via the SDK rather
+ * than through wagmi's own `connect()`.
+ */
+export function flowConnector(parameters = {}) {
+    let flow = parameters.flow ?? null;
+    return createConnector((config) => {
+        const getFlow = () => {
+            if (flow)
+                return flow;
+            const singleton = getSingletonFlow();
+            if (singleton) {
+                flow = singleton;
+                return flow;
+            }
+            const { flow: _omit, ...rest } = parameters;
+            flow = createFlow({
+                ...rest,
+                chains: [...config.chains],
+            });
+            return flow;
+        };
+        return {
+            id: "flow",
+            name: "Flow",
+            type: flowConnector.type,
+            async setup() {
+                const f = getFlow();
+                let lastAddress = null;
+                f.subscribe((state) => {
+                    const next = state.address ? getAddress(state.address) : null;
+                    if (next === lastAddress)
+                        return;
+                    lastAddress = next;
+                    if (next) {
+                        config.emitter.emit("connect", {
+                            accounts: [next],
+                            chainId: config.chains[0]?.id ?? 1,
+                        });
+                    }
+                    else {
+                        config.emitter.emit("disconnect");
+                    }
+                });
+            },
+            async connect(params = {}) {
+                const f = getFlow();
+                const isReconnecting = params.isReconnecting;
+                // Wagmi calls connect({ isReconnecting: true }) on mount when it
+                // thinks there's a previous session. Without this branch we'd open
+                // the dialog (full sign-in) on every page load. Silent restore
+                // handles it without UI; if there's no session, surface that as a
+                // throw so wagmi treats the connector as disconnected.
+                if (!f.isAuthenticated) {
+                    if (isReconnecting) {
+                        const restored = await f.restore();
+                        if (!restored) {
+                            throw new Error("No active session to restore");
+                        }
+                    }
+                    else {
+                        await f.login();
+                    }
+                }
+                const address = f.address;
+                if (!address)
+                    throw new Error("Failed to connect");
+                const chainId = params.chainId ?? config.chains[0]?.id;
+                if (chainId == null) {
+                    throw new Error("Flow connector requires at least one chain to be configured");
+                }
+                return {
+                    accounts: [getAddress(address)],
+                    chainId,
+                };
+            },
+            async disconnect() {
+                await flow?.logout();
+            },
+            async getAccounts() {
+                const f = getFlow();
+                if (!f.address)
+                    return [];
+                return [getAddress(f.address)];
+            },
+            async getChainId() {
+                return config.chains[0]?.id ?? 1;
+            },
+            async isAuthorized() {
+                try {
+                    const accounts = await this.getAccounts();
+                    return accounts.length > 0;
+                }
+                catch {
+                    return false;
+                }
+            },
+            async switchChain({ chainId }) {
+                const chain = config.chains.find((c) => c.id === chainId);
+                if (!chain)
+                    throw new SwitchChainError(new Error("Chain not configured"));
+                return chain;
+            },
+            async getClient({ chainId } = {}) {
+                const f = getFlow();
+                return f.walletClient({ ...(chainId ? { chainId } : {}) });
+            },
+            async getProvider({ chainId } = {}) {
+                const client = await this.getClient({ ...(chainId ? { chainId } : {}) });
+                return { request: client.request };
+            },
+            onAccountsChanged() { },
+            onChainChanged(chain) {
+                config.emitter.emit("change", { chainId: Number(chain) });
+            },
+            async onDisconnect() {
+                await flow?.logout();
+            },
+        };
+    });
+}

package/package.json

@@ -0,0 +1,99 @@
+{
+  "name": "@flow-industries/id",
+  "version": "0.2.0",
+  "module": "src/index.ts",
+  "type": "module",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/sdk/client/index.d.ts",
+      "import": "./dist/sdk/client/index.js"
+    },
+    "./react": {
+      "types": "./dist/sdk/react/index.d.ts",
+      "import": "./dist/sdk/react/index.js"
+    },
+    "./wagmi": {
+      "types": "./dist/sdk/wagmi/index.d.ts",
+      "import": "./dist/sdk/wagmi/index.js"
+    },
+    "./chains": {
+      "types": "./dist/sdk/chains.d.ts",
+      "import": "./dist/sdk/chains.js"
+    },
+    "./verify": {
+      "types": "./dist/sdk/verify.d.ts",
+      "import": "./dist/sdk/verify.js"
+    }
+  },
+  "files": [
+    "dist/sdk"
+  ],
+  "scripts": {
+    "dev": "bunx vite & bunx vite --config vite.playground.config.ts & bunx vite --config vite.landing.config.ts & bun run --watch src/index.ts",
+    "dev:dialog": "bunx vite",
+    "dev:playground": "bunx vite --config vite.playground.config.ts",
+    "dev:landing": "bunx vite --config vite.landing.config.ts",
+    "build:dialog": "bunx vite build",
+    "build:playground": "bunx vite build --config vite.playground.config.ts",
+    "build:landing": "bunx vite build --config vite.landing.config.ts",
+    "build": "bunx vite build && bunx vite build --config vite.playground.config.ts && bunx vite build --config vite.landing.config.ts",
+    "build:sdk": "tsc --project tsconfig.sdk.json",
+    "prepublishOnly": "bun run build:sdk",
+    "start": "bun run src/index.ts",
+    "db:generate": "bunx @better-auth/cli generate",
+    "db:migrate": "bunx drizzle-kit generate && bunx drizzle-kit migrate",
+    "db:push": "bunx drizzle-kit push",
+    "db:studio": "bunx drizzle-kit studio"
+  },
+  "peerDependencies": {
+    "viem": ">=2.47.10",
+    "ox": ">=0.14.0",
+    "react": ">=18",
+    "@wagmi/core": ">=3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": { "optional": true },
+    "@wagmi/core": { "optional": true }
+  },
+  "devDependencies": {
+    "@better-auth/cli": "^1.4.17",
+    "@tailwindcss/vite": "^4.1.18",
+    "@tanstack/react-router-devtools": "^1.160.0",
+    "@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",
+    "tailwindcss": "^4.1.18",
+    "tw-animate-css": "^1.4.0",
+    "typescript": "^5",
+    "vite": "^7.3.1"
+  },
+  "dependencies": {
+    "@flow-industries/ui": "^0.11.1",
+    "@tanstack/query-sync-storage-persister": "^5.90.22",
+    "@tanstack/react-query": "^5.90.20",
+    "@tanstack/react-query-persist-client": "^5.90.22",
+    "@tanstack/react-router": "^1.160.0",
+    "better-auth": "^1.4.17",
+    "drizzle-orm": "^0.45.1",
+    "geist": "^1.7.0",
+    "hono": "^4.11.5",
+    "jose": "^6.1.3",
+    "lucide-react": "^0.563.0",
+    "motion": "^12.33.0",
+    "postgres": "^3.4.8",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "react-intersection-observer": "^10.0.2",
+    "tempo.ts": "^0.14.2",
+    "viem": "2.47.10",
+    "wagmi": "^3.4.2",
+    "zustand": "^5.0.11"
+  }
+}