@flow-industries/id 0.22.1 → 0.23.1

package/README.md

@@ -37,15 +37,24 @@ bun add @flow-industries/id wagmi viem @tanstack/react-query
 
 ## Documentation
 
-Full documentation at **[docs.flow.industries/en/auth](https://docs.flow.industries/en/auth)**.
+- [Integration guide](docs/integration-guide.md) — server setup, canonical sign-in, React, and account navigation.
+- [Guest sessions](docs/guest-sessions.md) — silent guest creation and preserving identity during signup.
+- [Action sessions](docs/action-sessions.md) — activity timing and the inline action widget.
 
-- [Getting started](https://docs.flow.industries/en/auth/getting-started) - install the SDK and ship a login button
-- [Concepts](https://docs.flow.industries/en/auth/concepts) - passkeys, audience-bound JWTs, sessions, and access keys
-- [SDK](https://docs.flow.industries/en/auth/sdk/create-flow) - `createFlow`, React hooks, Wagmi connector, and direct dialog control
-- [Wagmi](https://docs.flow.industries/en/auth/sdk/wagmi) - use Flow ID as a Wagmi connector
-- [Signing](https://docs.flow.industries/en/auth/signing) - messages, typed data, transactions, and batch calls
-- [JWT verify](https://docs.flow.industries/en/auth/jwt-verify) - verify Flow sessions on your backend
-- [API reference](https://docs.flow.industries/en/auth/api) and [self-hosting](https://docs.flow.industries/en/auth/self-hosting)
+The Auth pages in the separate documentation repository are archived. Use the
+guides here for the current SDK integration.
+
+## Sign-in and account pages
+
+The SDK starts sign-in through your app's first-party `/flow/session` handler
+and navigates to Flow ID's `/authorize` page. Completion returns to the saved
+app path; read the new session after navigation instead of continuing after
+`await flow.login()`.
+
+`ProfileButton` and `flow.openAccount()` open `/account` in a normal new tab.
+The source app stays loaded and refreshes its session on refocus. Sign-in and
+own-account management no longer use an embedded dialog. See the
+[integration guide](docs/integration-guide.md) for server wiring and migration.
 
 ## Public profile overlays
 
@@ -134,3 +143,5 @@ The current OpenAPI artifact describes the service report boundary. The remainin
 account, room management, study, settings, session and passkey HTTP operations
 still need complete request/response descriptions and generated client coverage
 before the full HTTP contract work is complete.
+
+Server deployments may set `FLOW_ID_API_URL` to a trusted internal HTTP(S) origin for API and JWKS requests, or pass `apiUrl` to server session/verification helpers. `issuerUrl` remains the public JWT issuer and browser navigation origin. The transport URL must contain no credentials, path, query, or fragment.

package/dist/sdk/browser-contract.d.ts

@@ -0,0 +1,30 @@
+import { z } from "zod";
+export declare const browserSigningSchema: z.ZodObject<{
+    signature: z.ZodObject<{
+        r: z.ZodString;
+        s: z.ZodString;
+    }, z.core.$strip>;
+    metadata: z.ZodObject<{
+        authenticatorData: z.ZodString;
+        clientDataJSON: z.ZodString;
+        challengeIndex: z.ZodNumber;
+        typeIndex: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const browserCompletionSchema: z.ZodObject<{
+    loginId: z.ZodString;
+    userId: z.ZodString;
+    expires: z.ZodNumber;
+    webauthn: z.ZodOptional<z.ZodObject<{
+        signature: z.ZodObject<{
+            r: z.ZodString;
+            s: z.ZodString;
+        }, z.core.$strip>;
+        metadata: z.ZodObject<{
+            authenticatorData: z.ZodString;
+            clientDataJSON: z.ZodString;
+            challengeIndex: z.ZodNumber;
+            typeIndex: z.ZodNumber;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;

package/dist/sdk/browser-contract.js

@@ -0,0 +1,19 @@
+import { z } from "zod";
+export const browserSigningSchema = z.object({
+    signature: z.object({
+        r: z.string().regex(/^\d+$/),
+        s: z.string().regex(/^\d+$/),
+    }),
+    metadata: z.object({
+        authenticatorData: z.string().max(2048),
+        clientDataJSON: z.string().max(4096),
+        challengeIndex: z.number().int().nonnegative(),
+        typeIndex: z.number().int().nonnegative(),
+    }),
+});
+export const browserCompletionSchema = z.object({
+    loginId: z.string(),
+    userId: z.string(),
+    expires: z.number(),
+    webauthn: browserSigningSchema.optional(),
+});

package/dist/sdk/browser-session-route.d.ts

@@ -0,0 +1,8 @@
+export declare function safeReturnTo(value: string, audience: string, sessionPath?: string): string | null;
+export declare function startBrowserSession(request: Request, audience: string, issuerUrl: string, body: {
+    action: "login" | "account";
+    returnTo?: string;
+    signUp?: boolean;
+    accessKeyHash?: string;
+}, apiUrl?: string): Promise<Response>;
+export declare function finishBrowserSession(request: Request, audience: string, issuerUrl: string, apiUrl?: string): Promise<Response>;

package/dist/sdk/browser-session-route.js

@@ -0,0 +1,201 @@
+import { z } from "zod";
+import { browserSigningSchema } from "./browser-contract";
+import { clearCookieString, cookieNamesFor, parseCookieHeader, serializeCookie, } from "./cookies";
+import { fetchIssuerApi, resolveIssuerApiUrl } from "./issuer-api";
+import { claimsToUser, sessionCookies } from "./session-core";
+import { verifyFlowJWT } from "./verify";
+const opaquePattern = /^[A-Za-z0-9_-]{43}$/;
+const pendingSchema = z.object({
+    state: z.string().regex(opaquePattern),
+    verifier: z.string().regex(opaquePattern),
+    returnTo: z.string(),
+    expires: z.number(),
+});
+const exchangeSchema = z.object({
+    jwt: z.string(),
+    refreshToken: z.string(),
+    webauthn: browserSigningSchema.optional(),
+});
+function base64Url(bytes) {
+    return btoa(String.fromCharCode(...bytes))
+        .replaceAll("+", "-")
+        .replaceAll("/", "_")
+        .replaceAll("=", "");
+}
+function secret() {
+    return base64Url(crypto.getRandomValues(new Uint8Array(32)));
+}
+async function pkce(value) {
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(value));
+    return base64Url(new Uint8Array(digest));
+}
+function cookieName(audience, state) {
+    return `${cookieNamesFor(audience).refresh}.login_${state}`;
+}
+function reply(data, status = 200, cookies = []) {
+    const headers = new Headers({
+        "Content-Type": "application/json",
+        "Cache-Control": "no-store",
+        "Referrer-Policy": "no-referrer",
+    });
+    for (const cookie of cookies)
+        headers.append("Set-Cookie", cookie);
+    return new Response(JSON.stringify(data), { status, headers });
+}
+export function safeReturnTo(value, audience, sessionPath = "/flow/session") {
+    if (!value.startsWith("/") ||
+        value.startsWith("//") ||
+        value.includes("\\") ||
+        Array.from(value).some((character) => {
+            const code = character.charCodeAt(0);
+            return code < 32 || code === 127;
+        }))
+        return null;
+    try {
+        const url = new URL(value, audience);
+        if (url.origin !== audience || url.pathname === sessionPath)
+            return null;
+        return `${url.pathname}${url.search}${url.hash}`;
+    }
+    catch {
+        return null;
+    }
+}
+export async function startBrowserSession(request, audience, issuerUrl, body, apiUrl = resolveIssuerApiUrl(issuerUrl)) {
+    const cookies = parseCookieHeader(request.headers.get("Cookie"));
+    const refresh = cookies[cookieNamesFor(audience).refresh];
+    const headers = new Headers({ "Content-Type": "application/json" });
+    if (refresh)
+        headers.set("Authorization", `Bearer ${refresh}`);
+    for (const name of ["cf-connecting-ip", "x-forwarded-for", "user-agent"]) {
+        const value = request.headers.get(name);
+        if (value)
+            headers.set(name, value);
+    }
+    if (body.action === "account") {
+        if (!refresh)
+            return reply({ error: "signed_out" }, 401);
+        const response = await fetchIssuerApi(`${apiUrl}/api/auth/browser/account-handoff`, { method: "POST", headers, body: JSON.stringify({ audience }) });
+        if (!response.ok)
+            return reply({ error: "account_unavailable" }, response.status);
+        const { handoff } = z
+            .object({ handoff: z.string().regex(opaquePattern) })
+            .parse(await response.json());
+        return reply({ accountUrl: `${issuerUrl}/account#handoff=${handoff}` });
+    }
+    const returnTo = safeReturnTo(body.returnTo ?? "/", audience, new URL(request.url).pathname);
+    if (!returnTo)
+        return reply({ error: "invalid_return_destination" }, 400);
+    const state = secret();
+    const verifier = secret();
+    const callback = `${audience}${new URL(request.url).pathname}`;
+    const response = await fetchIssuerApi(`${apiUrl}/api/auth/browser/transaction`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+            audience,
+            callback,
+            state,
+            challenge: await pkce(verifier),
+            signUp: body.signUp ?? false,
+            accessKeyHash: body.accessKeyHash,
+        }),
+    });
+    if (!response.ok)
+        return reply({ error: "login_unavailable" }, response.status);
+    const { transaction } = z
+        .object({ transaction: z.string().regex(opaquePattern) })
+        .parse(await response.json());
+    const pending = btoa(encodeURIComponent(JSON.stringify({
+        state,
+        verifier,
+        returnTo,
+        expires: Date.now() + 600_000,
+    })));
+    return reply({
+        loginId: state,
+        authorizeUrl: `${issuerUrl}/authorize?transaction=${transaction}`,
+    }, 200, [
+        serializeCookie(cookieName(audience, state), pending, {
+            maxAge: 600,
+            secure: audience.startsWith("https:"),
+        }),
+    ]);
+}
+export async function finishBrowserSession(request, audience, issuerUrl, apiUrl = resolveIssuerApiUrl(issuerUrl)) {
+    const url = new URL(request.url);
+    const state = url.searchParams.get("flow_state") ?? "";
+    if (!opaquePattern.test(state))
+        return reply({ error: "invalid_login_state" }, 400);
+    const cookie = cookieName(audience, state);
+    const raw = parseCookieHeader(request.headers.get("Cookie"))[cookie];
+    let pending;
+    try {
+        pending = pendingSchema.parse(JSON.parse(decodeURIComponent(atob(raw ?? ""))));
+    }
+    catch {
+        return reply({ error: "login_expired" }, 400);
+    }
+    const returnTo = safeReturnTo(pending.returnTo, audience, new URL(request.url).pathname);
+    if (pending.state !== state || pending.expires <= Date.now() || !returnTo)
+        return reply({ error: "invalid_login_state" }, 400);
+    const clear = clearCookieString(cookie, {
+        secure: audience.startsWith("https:"),
+    });
+    const headers = new Headers({
+        "Cache-Control": "no-store",
+        "Referrer-Policy": "no-referrer",
+        Location: returnTo,
+    });
+    if (url.searchParams.get("flow_error") === "cancelled") {
+        headers.append("Set-Cookie", clear);
+        return new Response(null, { status: 303, headers });
+    }
+    const code = url.searchParams.get("flow_code") ?? "";
+    if (!opaquePattern.test(code))
+        return reply({ error: "invalid_login_code" }, 400);
+    try {
+        const result = await fetchIssuerApi(`${apiUrl}/api/auth/browser/token`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                code,
+                verifier: pending.verifier,
+                audience,
+                callback: `${audience}${url.pathname}`,
+            }),
+        });
+        if (!result.ok)
+            return reply({
+                error: "login_exchange_failed",
+                message: "Return to your app and start sign-in again.",
+            }, 400, [clear]);
+        const session = exchangeSchema.parse(await result.json());
+        const claims = await verifyFlowJWT(session.jwt, {
+            audience,
+            issuerUrl,
+            apiUrl,
+        });
+        if (!claimsToUser(claims).id)
+            throw new Error("Invalid session");
+        for (const value of sessionCookies(audience, session.jwt, session.refreshToken))
+            headers.append("Set-Cookie", value);
+        if (session.webauthn) {
+            const completion = btoa(encodeURIComponent(JSON.stringify({
+                loginId: state,
+                userId: claims.sub,
+                expires: Date.now() + 60_000,
+                webauthn: session.webauthn,
+            })));
+            headers.append("Set-Cookie", serializeCookie(`${cookieNamesFor(audience).refresh}.completion`, completion, { maxAge: 60, secure: audience.startsWith("https:") }));
+        }
+        headers.append("Set-Cookie", clear);
+        return new Response(null, { status: 303, headers });
+    }
+    catch {
+        return reply({
+            error: "login_exchange_unavailable",
+            message: "Return to your app and start sign-in again.",
+        }, 502, [clear]);
+    }
+}