@stwrd-auth/react 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this package are documented in this file.
+
+The format is based on Keep a Changelog 1.1.0, and this package adheres to Semantic Versioning (SemVer).
+
+## [0.1.0] - Unreleased
+
+Initial release.
+
+### Added
+
+- `StwrdProvider` and the `useSession`, `useUser` and `useOrganization` hooks, reading the session from `GET /auth/session`.
+- Session status `loading`, `authenticated`, `anonymous` and `unavailable`, with retries and cross-tab refresh.
+- Guard components: `SignedIn`, `SignedOut` and `Protect`.
+- Account components: `UserButton` and `OrganizationSwitcher`.
+- Types: `StwrdUser`, `StwrdOrganization`, `SessionResponse`, `StwrdState`, `ConsentState` and `OrganizationOption`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 stwrd
+
+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/README.md

@@ -1,3 +1,140 @@
-# Temporary Holding Version
+# @stwrd-auth/react
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+stwrd SDK for React (backend-for-frontend profile): a session provider, hooks and components that read the session from the `/auth/session` endpoint of your server.
+
+## What it is
+
+[stwrd](https://stwrd.dev) is a multi-tenant identity provider. In the backend-for-frontend (BFF) profile your server performs the OpenID Connect flow and keeps the tokens; the browser only holds a session cookie. This package is the front-end half: it asks your server who is signed in and exposes that to React components. It never sees a token.
+
+It needs a server that serves the `/auth/*` routes on the same origin as your front end: [`@stwrd-auth/node`](https://www.npmjs.com/package/@stwrd-auth/node) (Express), [`@stwrd-auth/workers`](https://www.npmjs.com/package/@stwrd-auth/workers) (Cloudflare Workers) or the Python SDK (`stwrd-auth` on PyPI). Authorization decisions stay on the server; the guards in this package only decide what to render.
+
+## Installation
+
+```sh
+npm install @stwrd-auth/react
+```
+
+Requires React 18 or newer (peer dependency) and a bundler that understands ESM. The package is ESM only and ships its own TypeScript declarations (install `@types/react` for TypeScript projects).
+
+## Minimal example
+
+```tsx
+import {
+  OrganizationSwitcher,
+  Protect,
+  SignedIn,
+  SignedOut,
+  StwrdProvider,
+  UserButton,
+  useSession,
+} from "@stwrd-auth/react";
+
+export function Home() {
+  const session = useSession();
+  if (session.status === "loading") return null;
+  if (session.status === "unavailable") return <p>Service unavailable.</p>;
+  return (
+    <>
+      <SignedOut>
+        <a href="/auth/sign-in?return_to=/">Sign in</a>
+      </SignedOut>
+      <SignedIn>
+        <p>Hello, {session.user?.display_name ?? session.user?.email}.</p>
+        <UserButton />
+        <OrganizationSwitcher /> {/* lists the person's organizations (needs the `org` scope) */}
+        <Protect role="org:admin" permission="members:invite" fallback={<p>No permission.</p>}>
+          <a href="/members">Members</a>
+        </Protect>
+      </SignedIn>
+    </>
+  );
+}
+
+export function App() {
+  return (
+    <StwrdProvider baseUrl="/auth">
+      <Home />
+    </StwrdProvider>
+  );
+}
+```
+
+Mount `App` as usual (`createRoot(document.getElementById("root")!).render(<App />)`). During development, proxy `/auth` to your server so that the cookie stays on one origin.
+
+## Configuration
+
+`StwrdProvider` takes one option:
+
+| Prop | Required | Default | Description |
+|---|---|---|---|
+| `baseUrl` | no | `/auth` | Where the server serves the routes; it must match the server's route prefix (`STWRD_PREFIX`). Changing it resets the session state. |
+
+The components render fixed English labels and expose `data-stwrd` attributes (`user-button`, `user-button-label`, `user-button-account-link`, `user-button-sign-out`, `organization-switcher`, `organization-switcher-select`, `organization-switcher-confirm`) as styling hooks. The `className` prop applies to the outer element.
+
+## API reference
+
+### Provider and hooks
+
+| Export | Description |
+|---|---|
+| `StwrdProvider` | Reads `GET {baseUrl}/session` with credentials, keeps the state and shares it with the tree. Other tabs are told to refresh when the session changes. |
+| `useSession()` | `{ status, user, organization, consents, accountUrl, refresh, signOut, listOrganizations, selectOrganization }` |
+| `useUser()` | The signed-in person, or `null`. |
+| `useOrganization()` | The active organization, or `null`. |
+
+`status` is one of:
+
+| Status | Meaning |
+|---|---|
+| `loading` | The first answer has not arrived. |
+| `authenticated` | A person is signed in. |
+| `anonymous` | Nobody is signed in. |
+| `unavailable` | The server could not answer, or answered something invalid. The last known state is kept. The provider retries three times with growing delays (2, 4 and 8 seconds). |
+
+While `unavailable`, `useUser()` and `useOrganization()` may still return the last known values; check `status` before using them for access decisions. `refresh()` asks the server again. `signOut()` navigates with a `POST` form to `{baseUrl}/sign-out`, including the CSRF token the server provided. `listOrganizations()` resolves to the person's organizations, or `null` when the server has organization selection disabled. `selectOrganization(id)` starts a real navigation through the server to switch the active organization.
+
+### Components
+
+| Component | Description |
+|---|---|
+| `SignedIn`, `SignedOut` | Render their children only when `status` is `authenticated` or `anonymous`. |
+| `Protect` | Renders its children when the person has every control given (`role`, `permission`, `condition(user)`); otherwise `fallback`. Capabilities come from the organization when there is one, otherwise from the individual lists. Renders nothing while `loading` or `unavailable`. |
+| `UserButton` | The person's name (or email, or id), a link to the account page and a sign-out button. |
+| `OrganizationSwitcher` | A selector with a confirm button when the person has several organizations; otherwise a link to the account page of the organization. |
+
+### Types
+
+`StwrdUser` (`id`, `email`, `email_verified`, `display_name`, `avatar_url`, `roles`, `permissions`), `StwrdOrganization` (`id`, `display_name`, `roles`, `permissions`), `SessionResponse`, `StwrdState`, `ConsentState` and `OrganizationOption`. `consents` is a map of consent names to `accepted`, `declined` or `pending`. `accountUrl` is the address of the person's account page.
+
+## Security
+
+- No token, claim or secret reaches the browser through this package. The session cookie is set by your server; the provider only sends `credentials: "include"` requests to `{baseUrl}/session` and `{baseUrl}/organizations`.
+- The provider accepts only a response with the exact expected shape and refuses anything else (status `unavailable`), including an `account_url` that is not an `http` or `https` URL.
+- Sign-out and the organization switch are `POST` navigations that include the CSRF token issued by the server.
+- The guards (`SignedIn`, `Protect`, ...) only change what is rendered. Enforce authorization on the server.
+- Components never show session content or the `Protect` fallback while the state is `loading` or `unavailable`.
+- Supported versions and how to report a vulnerability are described in the [security policy](https://github.com/stwrd-dev/sdk-js/security/policy).
+
+## Error handling and troubleshooting
+
+| Symptom | Cause | What to do |
+|---|---|---|
+| `status` stays `unavailable` | The server answered with an error, malformed JSON or a response that does not match the expected shape. | Check that `baseUrl` is the route prefix of your server and that `GET {baseUrl}/session` answers 200 JSON with `authenticated`, `user`, `organization`, `consents`, `csrf_token` and `account_url`. |
+| `status` is `anonymous` after sign-in | The cookie is not sent: different origin, or a development proxy missing. | Serve the front end and the routes from one origin. |
+| `OrganizationSwitcher` shows a link, not a selector | The person has one organization, or organization selection is not enabled. | Add `org` to the server scope (`STWRD_SCOPE`) and allow it for the application. |
+| `useSession() ... was used outside <StwrdProvider>` | A hook or component is rendered outside the provider. | Wrap the tree in `StwrdProvider`. |
+
+## Compatibility
+
+- React 18 or newer (the test suite runs against React 18).
+- ESM only; TypeScript declarations included.
+- Browsers that support `fetch`. `BroadcastChannel` is used for cross-tab updates when available.
+- Server side: a BFF that serves `GET /auth/session` in the documented shape. There is no Next.js adapter yet.
+
+## Versioning
+
+This package follows Semantic Versioning (SemVer). While the version is below 1.0, minor releases may contain breaking changes. Changes are listed in `CHANGELOG.md`.
+
+## License
+
+MIT © 2026 stwrd. See `LICENSE`.

package/dist/StwrdProvider.d.ts

@@ -0,0 +1,16 @@
+import { type ReactNode } from "react";
+import type { OrganizationOption, StwrdState } from "./types.js";
+export type StwrdContextValue = StwrdState & {
+    refresh(): Promise<void>;
+    signOut(): void;
+    /** The person's own organizations; `null` when organization selection is not enabled on the BFF. */
+    listOrganizations(): Promise<OrganizationOption[] | null>;
+    /** Starts a real OIDC navigation for the chosen organization; the page leaves. */
+    selectOrganization(id: string): void;
+};
+export interface StwrdProviderProps {
+    baseUrl?: string;
+    children?: ReactNode;
+}
+export declare function StwrdProvider({ baseUrl, children }: StwrdProviderProps): import("react").JSX.Element;
+export declare function useSessionContext(): StwrdContextValue;

package/dist/StwrdProvider.js

@@ -0,0 +1,175 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useCallback, useContext, useEffect, useRef, useState } from "react";
+const Context = createContext(null);
+const empty = () => ({ status: "loading", user: null, organization: null, consents: {}, accountUrl: "" });
+const backoff = [2000, 4000, 8000];
+// Other tabs only ever receive "something changed, ask again": never tokens or claims.
+const CHANNEL = "stwrd:session";
+const CHANGED_FLAG = "stwrd:session-changed";
+function organizationOptions(v) {
+    if (!record(v) || !Array.isArray(v.organizations))
+        return null;
+    const list = v.organizations;
+    return list.every(o => record(o) && keys(o, ["id", "display_name", "current"]) && nonempty(o.id) && nullableString(o.display_name) && typeof o.current === "boolean") ? list : null;
+}
+const record = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const keys = (v, expected) => Object.keys(v).length === expected.length && expected.every(k => Object.hasOwn(v, k));
+const strings = (v) => Array.isArray(v) && v.every(x => typeof x === "string");
+const nullableString = (v) => v === null || typeof v === "string";
+/** A rendered `href` must never carry a `javascript:` (or any non-web) scheme. */
+const webUrl = (v) => { if (!nonempty(v))
+    return false; try {
+    const p = new URL(v, "https://placeholder.invalid").protocol;
+    return p === "https:" || p === "http:";
+}
+catch {
+    return false;
+} };
+const nonempty = (v) => typeof v === "string" && v.trim().length > 0;
+/** Reject incomplete, legacy and contradictory browser responses before publishing authority. */
+function valid(v) {
+    if (!record(v) || !keys(v, ["authenticated", "user", "organization", "consents", "csrf_token", "account_url"]) || typeof v.authenticated !== "boolean" || !webUrl(v.account_url) || !record(v.consents) || !Object.values(v.consents).every(x => x === "accepted" || x === "declined" || x === "pending"))
+        return false;
+    if (!v.authenticated)
+        return v.user === null && v.organization === null && v.csrf_token === null && Object.keys(v.consents).length === 0;
+    const u = v.user, o = v.organization;
+    if (!record(u) || !keys(u, ["id", "email", "email_verified", "display_name", "avatar_url", "roles", "permissions"]) || !nonempty(u.id) || !nullableString(u.email) || typeof u.email_verified !== "boolean" || !nullableString(u.display_name) || !nullableString(u.avatar_url) || !strings(u.roles) || !strings(u.permissions) || !nonempty(v.csrf_token))
+        return false;
+    return o === null || (record(o) && keys(o, ["id", "display_name", "roles", "permissions"]) && nonempty(o.id) && nonempty(o.display_name) && strings(o.roles) && strings(o.permissions) && u.roles.length === 0 && u.permissions.length === 0);
+}
+export function StwrdProvider({ baseUrl = "/auth", children }) {
+    const [state, setState] = useState(empty);
+    const csrf = useRef(null);
+    // Stable callbacks always target the committed configuration, including retained references.
+    const currentBaseUrl = useRef(baseUrl);
+    const generation = useRef(0);
+    const signingOut = useRef(false);
+    const [attempt, setAttempt] = useState(0);
+    const channel = useRef(null);
+    const refresh = useCallback(async () => {
+        if (signingOut.current)
+            return;
+        const request = ++generation.current;
+        try {
+            const response = await fetch(`${currentBaseUrl.current}/session`, { credentials: "include", cache: "no-store" });
+            if (!response.ok)
+                throw new Error("Session unavailable");
+            const body = await response.json();
+            if (!valid(body))
+                throw new Error("Invalid session response");
+            if (request !== generation.current)
+                return;
+            csrf.current = body.csrf_token;
+            const snapshot = { user: body.user, organization: body.organization, consents: body.consents, accountUrl: body.account_url };
+            setState(body.authenticated ? { ...snapshot, status: "authenticated", user: body.user } : { ...snapshot, status: "anonymous", user: null, organization: null });
+        }
+        catch {
+            if (request === generation.current)
+                setState(previous => ({ ...previous, status: "unavailable" }));
+        }
+    }, []);
+    useEffect(() => {
+        currentBaseUrl.current = baseUrl;
+        signingOut.current = false;
+        csrf.current = null;
+        setState(empty());
+        setAttempt(0);
+        void refresh();
+        return () => { ++generation.current; };
+    }, [baseUrl, refresh]);
+    useEffect(() => {
+        if (typeof BroadcastChannel === "undefined")
+            return;
+        const bus = new BroadcastChannel(CHANNEL);
+        channel.current = bus;
+        bus.onmessage = () => { void refresh(); };
+        try {
+            // A navigation that changed the session (organization switch, sign-out) set this flag
+            // before leaving; the page it lands on tells the other tabs once.
+            if (sessionStorage.getItem(CHANGED_FLAG)) {
+                sessionStorage.removeItem(CHANGED_FLAG);
+                bus.postMessage("changed");
+            }
+        }
+        catch { /* storage unavailable: other tabs refresh on their own schedule */ }
+        return () => { bus.close(); channel.current = null; };
+    }, [refresh]);
+    useEffect(() => {
+        // The only other signal is the BroadcastChannel notice, which a hidden, frozen or
+        // restored tab can miss: ask again whenever the tab becomes visible or comes back
+        // from the back/forward cache.
+        const onVisible = () => { if (document.visibilityState === "visible")
+            void refresh(); };
+        const onPageShow = (event) => { if (event.persisted)
+            void refresh(); };
+        document.addEventListener("visibilitychange", onVisible);
+        window.addEventListener("pageshow", onPageShow);
+        return () => { document.removeEventListener("visibilitychange", onVisible); window.removeEventListener("pageshow", onPageShow); };
+    }, [refresh]);
+    useEffect(() => {
+        if (state.status !== "unavailable") {
+            setAttempt(0);
+            return;
+        }
+        if (attempt >= backoff.length || signingOut.current)
+            return;
+        const timer = setTimeout(() => { setAttempt(n => n + 1); void refresh(); }, backoff[attempt]);
+        return () => clearTimeout(timer);
+    }, [state.status, attempt, refresh]);
+    const markChanged = () => { try {
+        sessionStorage.setItem(CHANGED_FLAG, "1");
+    }
+    catch { /* optional */ } };
+    const post = (action, fields) => {
+        const form = document.createElement("form");
+        form.method = "POST";
+        form.action = `${currentBaseUrl.current}/${action}`;
+        form.style.display = "none";
+        for (const [name, value] of Object.entries(fields)) {
+            const field = document.createElement("input");
+            field.type = "hidden";
+            field.name = name;
+            field.value = value;
+            form.appendChild(field);
+        }
+        document.body.appendChild(form);
+        // A real navigation follows the BFF/IdP redirect chain; fetch would not.
+        form.submit();
+    };
+    const listOrganizations = useCallback(async () => {
+        const response = await fetch(`${currentBaseUrl.current}/organizations`, { credentials: "include", cache: "no-store" });
+        if (response.status === 404)
+            return null;
+        // The session ended after `/session` was read: show the truth, not a stale "signed in".
+        if (response.status === 401) {
+            void refresh();
+            return null;
+        }
+        if (!response.ok)
+            throw new Error("Organizations unavailable");
+        const options = organizationOptions(await response.json());
+        if (options === null)
+            throw new Error("Invalid organizations response");
+        return options;
+    }, [refresh]);
+    const selectOrganization = useCallback((id) => {
+        if (signingOut.current || !csrf.current)
+            return;
+        markChanged();
+        post("organization", { csrf_token: csrf.current, organization_id: id, return_to: `${window.location.pathname}${window.location.search}` });
+    }, []);
+    const signOut = useCallback(() => {
+        signingOut.current = true;
+        ++generation.current;
+        setState(previous => ({ ...previous, status: "loading" }));
+        markChanged();
+        post("sign-out", { csrf_token: csrf.current ?? "" });
+    }, []);
+    return _jsx(Context.Provider, { value: { ...state, refresh, signOut, listOrganizations, selectOrganization }, children: children });
+}
+export function useSessionContext() {
+    const value = useContext(Context);
+    if (!value)
+        throw new Error("useSession() (or a stwrd component) was used outside <StwrdProvider>.");
+    return value;
+}

package/dist/components.d.ts

@@ -0,0 +1,26 @@
+import { type ReactElement, type ReactNode } from "react";
+import type { StwrdUser } from "./types.js";
+export interface SignedInProps {
+    children?: ReactNode;
+}
+export declare function SignedIn({ children }: SignedInProps): ReactElement | null;
+export interface SignedOutProps {
+    children?: ReactNode;
+}
+export declare function SignedOut({ children }: SignedOutProps): ReactElement | null;
+export interface ProtectProps {
+    role?: string;
+    permission?: string;
+    condition?: (user: StwrdUser) => boolean;
+    fallback?: ReactNode;
+    children?: ReactNode;
+}
+export declare function Protect({ role, permission, condition, fallback, children }: ProtectProps): ReactElement | null;
+export interface UserButtonProps {
+    className?: string;
+}
+export declare function UserButton({ className }: UserButtonProps): ReactElement | null;
+export interface OrganizationSwitcherProps {
+    className?: string;
+}
+export declare function OrganizationSwitcher({ className, }: OrganizationSwitcherProps): ReactElement | null;

package/dist/components.js

@@ -0,0 +1,79 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useState } from "react";
+import { useSession } from "./useSession.js";
+export function SignedIn({ children }) {
+    const { status } = useSession();
+    if (status !== "authenticated") {
+        return null;
+    }
+    return _jsx(_Fragment, { children: children });
+}
+export function SignedOut({ children }) {
+    const { status } = useSession();
+    if (status !== "anonymous") {
+        return null;
+    }
+    return _jsx(_Fragment, { children: children });
+}
+export function Protect({ role, permission, condition, fallback = null, children }) {
+    const { user, organization, status } = useSession();
+    if (status === "loading" || status === "unavailable") {
+        // `unavailable` is handled with `loading`, not with `user === null`: the
+        // `fallback` is what a person WITHOUT permission sees, and whether this
+        // person has it is not known.
+        return null;
+    }
+    if (user === null) {
+        return _jsx(_Fragment, { children: fallback });
+    }
+    const capabilities = organization ?? user;
+    if ((role !== undefined && !capabilities.roles.includes(role)) || (permission !== undefined && !capabilities.permissions.includes(permission)) || (condition && !condition(user))) {
+        return _jsx(_Fragment, { children: fallback });
+    }
+    return _jsx(_Fragment, { children: children });
+}
+export function UserButton({ className }) {
+    const { user, accountUrl, signOut, status } = useSession();
+    if (status !== "authenticated") {
+        return null;
+    }
+    const label = user.display_name ?? user.email ?? user.id;
+    return (_jsxs("div", { className: className, "data-stwrd": "user-button", children: [_jsx("span", { "data-stwrd": "user-button-label", children: label }), _jsx("a", { href: accountUrl, "data-stwrd": "user-button-account-link", children: "Account" }), _jsx("button", { type: "button", onClick: signOut, "data-stwrd": "user-button-sign-out", children: "Sign out" })] }));
+}
+/** Two organizations can share a display name; the id tells them apart. */
+function optionLabel(option, all) {
+    const name = option.display_name ?? option.id;
+    const repeated = all.filter(other => (other.display_name ?? other.id) === name).length > 1;
+    return repeated && option.display_name !== null ? `${name} (${option.id.slice(0, 8)})` : name;
+}
+export function OrganizationSwitcher({ className, }) {
+    const { organization, accountUrl, status, user, listOrganizations, selectOrganization } = useSession();
+    const [options, setOptions] = useState(null);
+    const [pending, setPending] = useState(null);
+    const signedIn = status === "authenticated" && organization !== null;
+    const identity = signedIn ? `${user?.id}:${organization?.id}` : null;
+    useEffect(() => {
+        // A late answer for a previous identity or status is dropped; losing
+        // authority (503) or the session clears the list.
+        setOptions(null);
+        setPending(null);
+        if (identity === null)
+            return;
+        let current = true;
+        listOrganizations().then(list => { if (current)
+            setOptions(list); }, () => { if (current)
+            setOptions(null); });
+        return () => { current = false; };
+    }, [identity, listOrganizations]);
+    if (!signedIn || organization === null) {
+        return null;
+    }
+    if (options !== null && options.length > 1) {
+        // Choosing and confirming are two acts: a key press on a closed <select>
+        // fires `change` at once, and the navigation would drop unsaved work.
+        const chosen = pending ?? organization.id;
+        return (_jsxs("span", { className: className, "data-stwrd": "organization-switcher", children: [_jsxs("select", { "aria-label": "Organization", "data-stwrd": "organization-switcher-select", onChange: event => setPending(event.target.value), value: options.some(option => option.id === chosen) ? chosen : "", children: [options.every(option => option.id !== organization.id) && _jsx("option", { disabled: true, value: "", children: organization.display_name }), options.map(option => _jsx("option", { value: option.id, children: optionLabel(option, options) }, option.id))] }), _jsx("button", { type: "button", "data-stwrd": "organization-switcher-confirm", disabled: pending === null || pending === organization.id, onClick: () => { if (pending !== null && pending !== organization.id)
+                        selectOrganization(pending); }, children: "Switch" })] }));
+    }
+    return (_jsx("a", { className: className, "data-stwrd": "organization-switcher", href: `${accountUrl}/organizations`, children: organization.display_name }));
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `@stwrd-auth/react` — the React SDK, BFF mode: the provider, the session
+ * hooks and the guard and account components.
+ */
+export { StwrdProvider } from "./StwrdProvider.js";
+export type { StwrdProviderProps } from "./StwrdProvider.js";
+export { useSession, useUser, useOrganization } from "./useSession.js";
+export { OrganizationSwitcher, Protect, SignedIn, SignedOut, UserButton } from "./components.js";
+export type { OrganizationSwitcherProps, ProtectProps, SignedInProps, SignedOutProps, UserButtonProps, } from "./components.js";
+export type { ConsentState, OrganizationOption, SessionResponse, StwrdState, StwrdUser, StwrdOrganization } from "./types.js";

package/dist/index.js

@@ -0,0 +1,7 @@
+/**
+ * `@stwrd-auth/react` — the React SDK, BFF mode: the provider, the session
+ * hooks and the guard and account components.
+ */
+export { StwrdProvider } from "./StwrdProvider.js";
+export { useSession, useUser, useOrganization } from "./useSession.js";
+export { OrganizationSwitcher, Protect, SignedIn, SignedOut, UserButton } from "./components.js";

package/dist/types.d.ts

@@ -0,0 +1,47 @@
+export type ConsentState = "accepted" | "declined" | "pending";
+export interface StwrdUser {
+    id: string;
+    email: string | null;
+    email_verified: boolean;
+    display_name: string | null;
+    avatar_url: string | null;
+    roles: string[];
+    permissions: string[];
+}
+export interface StwrdOrganization {
+    id: string;
+    display_name: string;
+    roles: string[];
+    permissions: string[];
+}
+export interface SessionResponse {
+    authenticated: boolean;
+    user: StwrdUser | null;
+    organization: StwrdOrganization | null;
+    consents: Record<string, ConsentState>;
+    csrf_token: string | null;
+    account_url: string;
+}
+interface Snapshot {
+    user: StwrdUser | null;
+    organization: StwrdOrganization | null;
+    consents: Record<string, ConsentState>;
+    accountUrl: string;
+}
+export type StwrdState = (Snapshot & {
+    status: "loading" | "unavailable";
+}) | (Snapshot & {
+    status: "authenticated";
+    user: StwrdUser;
+}) | (Snapshot & {
+    status: "anonymous";
+    user: null;
+    organization: null;
+});
+/** One of the signed-in person's own organizations, as listed by the BFF. */
+export interface OrganizationOption {
+    id: string;
+    display_name: string | null;
+    current: boolean;
+}
+export {};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/useSession.d.ts

@@ -0,0 +1,3 @@
+export declare function useSession(): import("./StwrdProvider.js").StwrdContextValue;
+export declare function useUser(): import("./types.js").StwrdUser | null;
+export declare function useOrganization(): import("./types.js").StwrdOrganization | null;

package/dist/useSession.js

@@ -0,0 +1,4 @@
+import { useSessionContext } from "./StwrdProvider.js";
+export function useSession() { return useSessionContext(); }
+export function useUser() { return useSession().user; }
+export function useOrganization() { return useSession().organization; }

package/package.json

@@ -1,6 +1,74 @@
 {
   "name": "@stwrd-auth/react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "stwrd SDK for React (backend-for-frontend profile): a session provider, hooks and components that read the session from the /auth/session endpoint.",
+  "keywords": [
+    "stwrd",
+    "authentication",
+    "oidc",
+    "oauth2",
+    "react",
+    "bff",
+    "sessions",
+    "hooks"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "stwrd",
+    "url": "https://stwrd.dev"
+  },
+  "homepage": "https://stwrd.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stwrd-dev/sdk-js.git",
+    "directory": "packages/react"
+  },
+  "bugs": {
+    "url": "https://github.com/stwrd-dev/sdk-js/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "!dist/.tsbuildinfo",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "prepack": "npm run build",
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "lint": "tsc --noEmit -p tsconfig.json"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@testing-library/dom": "^10.4.0",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.1.0",
+    "@types/node": "^22.10.0",
+    "@types/react": "^18.3.0",
+    "@types/react-dom": "^18.3.0",
+    "jsdom": "^25.0.0",
+    "react": "^18.3.0",
+    "react-dom": "^18.3.0",
+    "typescript": "^5.6.0",
+    "vitest": "^4.1.10"
+  }
+}