@finueva/auth 0.8.0 → 0.9.0

package/README.md

@@ -1,157 +1,475 @@
-# @finueva/auth
+# `@finueva/auth`
 
-Experimental public SDK for Finueva Auth. Version `0.x` may introduce breaking changes; `1.0.0` will mark the stable interface.
+The official TypeScript client for Finueva Auth.
+
+Use it to:
+
+- sign users in with email and password;
+- read the current session;
+- manage profile and password details;
+- list organizations and accept invitations;
+- request short-lived Drive credentials;
+- authenticate CLIs and native applications.
+
+The package is ESM-only and has no runtime dependencies. Its API is experimental while the package is below `1.0.0`.
+
+## Install
 
 ```sh
 pnpm add @finueva/auth
 ```
 
-## Browser
+Node.js applications require Node.js 22 or later.
+
+## Pick The Right Client
+
+| Runtime                   | Import                 | How it authenticates                 |
+| ------------------------- | ---------------------- | ------------------------------------ |
+| Browser                   | `@finueva/auth`        | Finueva Auth's HTTP-only cookie      |
+| Server or SSR handler     | `@finueva/auth/server` | Cookies or one incoming bearer token |
+| CLI or native application | `@finueva/auth/device` | A device bearer session              |
+
+Create one browser client for the application, one server client per request, or one device client per application process.
+
+Before you start, ask the Auth operator to register your exact application origin. Device applications also need a registered client ID. Do not copy values from another application or environment.
+
+## Browser Quick Start
 
 ```ts
-import { createAuthClient } from "@finueva/auth";
+import { AuthError, createAuthClient } from "@finueva/auth";
 
 const auth = createAuthClient({
   authOrigin: "https://auth.finueva.com",
   appOrigin: window.location.origin,
 });
 
-if (auth._type !== "browser") throw new Error("Expected a browser Auth client");
+const session = await auth.getSession();
+
+if (session) {
+  console.log(`Signed in as ${session.user.email}`);
+} else {
+  console.log("Not signed in");
+}
+
+try {
+  const nextSession = await auth.signIn({
+    email: "ada@example.com",
+    password: "correct-horse-battery-staple",
+  });
+
+  console.log(`Welcome ${nextSession.user.name}`);
+} catch (error) {
+  if (error instanceof AuthError && error.code === "invalid_credentials") {
+    console.log("Check the email and password.");
+  } else {
+    throw error;
+  }
+}
+```
+
+Auth keeps the session token in an HTTP-only cookie. The browser client never returns that token.
 
+### React To Session Changes
+
+Use `onAuthStateChange()` to update the interface:
+
+```ts
 const stop = auth.onAuthStateChange((state) => {
-  if (state.status === "cached") renderSessionHint(state.session);
-  if (state.status === "authenticated") renderVerifiedSession(state.session);
+  switch (state.status) {
+    case "loading":
+      showLoading();
+      break;
+    case "cached":
+      showAccountHint(state.session.user);
+      break;
+    case "authenticated":
+      showAccount(state.session.user);
+      break;
+    case "unauthenticated":
+      showSignIn();
+      break;
+    case "unavailable":
+      showAuthUnavailable();
+      break;
+  }
 });
 
-const session = await auth.getSession();
-await auth.signUp(email, password, name);
-await auth.signIn({ email, password });
-await auth.signInWithSocialIdToken({ provider: "google", idToken, nonce, signUp: false });
-await auth.updateProfile({ name, image });
-await auth.changePassword(currentPassword, newPassword); // revokes other sessions by default
-await auth.requestPasswordReset(email, `${window.location.origin}/account/reset-password`);
-await auth.resetPassword(token, newPassword);
-await auth.sendVerificationEmail({
-  email,
-  callbackURL: `${window.location.origin}/account/email-verified`,
+window.addEventListener("pagehide", stop, { once: true });
+```
+
+`cached` state is only a display hint. Never use cached browser state to authorize an operation. Check access on the server.
+
+Browser snapshots use local storage by default. Choose another mode when you create the client:
+
+```ts
+const auth = createAuthClient({
+  authOrigin: "https://auth.finueva.com",
+  appOrigin: window.location.origin,
+  persistence: "session", // "local", "session", or "memory"
+  timeoutMs: 10_000,
 });
-const organizations = await auth.listOrganizations();
-const acceptance = await auth.acceptInvitation({ invitationId });
-const credential = await auth.getDriveCredential({
-  workspace: { type: "personal" },
+```
+
+The snapshot contains normalized display data, not cookies or Drive credentials.
+
+## Common Browser Tasks
+
+### Create An Account
+
+```ts
+const session = await auth.signUp("ada@example.com", "correct-horse-battery-staple", "Ada Lovelace");
+```
+
+New passwords must contain 10 to 128 characters.
+
+### Update The Profile
+
+```ts
+const session = await auth.updateProfile({
+  name: "Ada Lovelace",
+  image: "https://images.example.com/ada.png",
 });
-const organizationCredential = await auth.getDriveCredential({
-  workspace: { type: "organization", organizationId: organizations[0].id },
+```
+
+Pass `image: null` to remove the image.
+
+### Change The Password
+
+```ts
+await auth.changePassword(currentPassword, newPassword);
+```
+
+This revokes the user's other sessions by default. Pass `false` as the third argument only when the product deliberately keeps those sessions.
+
+### Reset A Password
+
+```ts
+await auth.requestPasswordReset("ada@example.com", `${window.location.origin}/account/reset-password`);
+```
+
+On the reset page, remove the token from the address bar before loading other resources. Use it once:
+
+```ts
+const url = new URL(window.location.href);
+let token = url.searchParams.get("token");
+
+url.searchParams.delete("token");
+window.history.replaceState(null, "", `${url.pathname}${url.search}${url.hash}`);
+
+if (!token) throw new Error("Reset token is missing");
+
+try {
+  await auth.resetPassword(token, newPassword);
+} finally {
+  token = null;
+}
+```
+
+Serve this page with `Cache-Control: no-store` and `Referrer-Policy: no-referrer`. Do not load analytics or third-party content on it.
+
+### Verify An Email
+
+```ts
+await auth.sendVerificationEmail({
+  email: "ada@example.com",
+  callbackURL: `${window.location.origin}/account/email-verified`,
 });
-await auth.signOut();
-stop();
 ```
 
-The Auth session uses the Auth-owned HTTP-only cookie. `getSession()` reports one bounded Better Auth authority result. Every authoritative session read receives a monotonic epoch, and account transitions advance that epoch again; only the newest read may update state or persistence, while a delayed older caller receives value-free `state_conflict`. `onSessionChange()` starts authoritative loading by itself and is an SDK-owned projection: it emits only sessions/null accepted through that bounded path, never Better Auth client cache state or persisted hints. The SDK subscribes once to Better Auth's session atom only as an invalidation source; focus, online, local mutation, and cross-tab storage signals trigger a coalesced bounded SDK `get-session` refresh, while raw `useSession.data` is ignored. Signals wait during account mutation, and the current sign-out signal cycle is suppressed so prior authority cannot race the owning transition. Better Auth `1.6.22` broadcasts sign-out between tabs but not sign-in, so a background tab observes sign-in on its next focus or online invalidation. Listener exceptions are isolated from authority work and other listeners. `onAuthStateChange()` separately emits `loading`, non-authoritative `cached`, authoritative `authenticated`/`unauthenticated`, or non-authoritative `unavailable`; it verifies every cache hint immediately.
+The callback must use the application's exact origin. Omit it to use the default Auth result page.
 
-`sendVerificationEmail({ email, callbackURL? })` sends one non-retried request. An explicit callback must be an exact absolute URL on `appOrigin`; it is never persisted by the SDK. Without one, the email lands on Auth's value-free verification result page after Better Auth completes verification.
+### List Organizations
 
-`signUp(email, password, name)`, `signIn({ email, password })`, `signInWithSocialIdToken({ provider, idToken, nonce?, signUp })`, `updateProfile({ name?, image? })`, and `changePassword(currentPassword, newPassword, revokeOtherSessions?)` delegate session ownership to Better Auth and return only the subsequently refreshed normalized session. Social providers are closed to `google | apple`, `signUp` is required, the ID token is copied and limited to 16 KiB, and an optional nonce is copied and limited to 256 printable ASCII bytes. At mutation start these methods synchronously invalidate the prior session ID, persisted-snapshot projection, auth-state and session-listener projections, and Drive authority. Physical browser-persistence removal is bounded best-effort asynchronous work. Only the bounded post-mutation refresh can publish the next session or null; refresh failure leaves the prior account absent and state unavailable. They never expose Better Auth's raw session token. Emails are trimmed and lowercased, names are trimmed, existing passwords accepted for sign-in or current-password proof contain 8 to 128 characters, new passwords require 10 to 128 characters, and a profile image must be `null` or one exact HTTPS URL (HTTP is accepted only on localhost). Profile updates require at least one field. SCIM-managed names remain provider-owned and cannot be changed through this method; image-only updates remain available.
+```ts
+let page = await auth.listOrganizations({ limit: 50 });
 
-`changePassword` defaults `revokeOtherSessions` to `true`, so Better Auth replaces the current session after removing the others. `requestPasswordReset(email, redirectTo)` requires an exact absolute callback on this client's `appOrigin`; the backend returns the same value-free success whether the account exists or not. `resetPassword(token, newPassword)` consumes Better Auth's one-time token, revokes existing sessions, and refreshes local authority. Password reset can therefore succeed even when a later session refresh is unavailable; do not automatically replay a consumed reset token.
+for (const organization of page.organizations) {
+  console.log(organization.id, organization.name, organization.slug);
+}
 
-`signOut()` returns `state_conflict` without making a request while an account mutation is active. Wait for that mutation to settle before signing out so a delayed mutation response cannot apply a later session cookie after a completed sign-out.
+if (page.nextCursor) {
+  page = await auth.listOrganizations({ limit: 50, cursor: page.nextCursor });
+}
+```
 
-DOM browsers use local storage by default. Set `persistence` to `"session"`, `"memory"`, or a structural driver with `getItem`, `setItem`, and `removeItem`; Workers and Node default to memory. The one 16 KiB versioned snapshot contains only a normalized session and its Auth authority identity. It expires with the session and never contains cookies, passwords, Drive credentials, tokens, headers, workspace selection, Better Auth payloads, or errors. Persistence failure cannot change an Auth request result.
+All organization collections use an opaque cursor and a page size from 1 through 100. Use
+`getOrganization()`, `listOrganizationMembers()`, `listOrganizationTeams()`, and
+`listOrganizationTeamMembers()` with an explicit organization ID. Manual owners and admins can use
+`listOrganizationInvitations()` and `getOrganizationInvitation()`. A verified recipient can use
+`listReceivedInvitations()` and `getReceivedInvitation()`.
 
-A workspace is either `{ type: "personal" }` or `{ type: "organization", organizationId }`; organization IDs must match `[A-Za-z0-9_-]{1,128}`. Workspace selections are strict and reject additional properties locally with `invalid_workspace_selection` before making a request.
+Pagination is deterministic while a collection does not change. During concurrent mutation, an
+insert at or before the cursor can be absent, an insert after it can appear once, and a delete,
+update, status change, or expiry can change later pages. Restart pagination when you need a current
+view.
 
-`listOrganizations()` returns strict current `{ id, name, slug }` records from Better Auth authority. Results are not cached or persisted. Because the current upstream endpoint is unpaginated and silently capped at 100 records, the SDK fails closed rather than return an ambiguous list when that cap is reached.
+### Accept An Invitation
 
-`acceptInvitation({ invitationId })` performs one non-retried Better Auth acceptance and returns only `{ organizationId }`. Invitation details, recipient email, inviter identity, membership payloads, and raw authority errors are never exposed or persisted. Unknown, expired, canceled, accepted, and concurrently claimed invitations all report the same value-free `invitation_unavailable` conflict.
+```ts
+const result = await auth.acceptInvitation({
+  invitationId: "invitation_01J8R7M6N5P4Q3S2T1",
+});
 
-The browser retains at most one completed Drive credential in memory and renews it once it has two minutes remaining. Concurrent requests for the same workspace share one credential request. Selecting a different workspace never reuses the completed or in-flight credential for the previous workspace and replaces the retained credential. Passing `forceRefresh: true` requests a replacement after a Drive authentication failure; the SDK never replays a Drive request.
+console.log(result.organizationId);
+```
 
-## Server
+### Sign Out
 
 ```ts
-import { createServerAuth } from "@finueva/auth/server";
+await auth.signOut();
+```
 
-const auth = createServerAuth({
-  authOrigin: "https://auth.finueva.com",
-  appOrigin: "https://files.finueva.com",
-  request,
+## Request A Drive Credential
+
+Ask Auth for a credential for one workspace:
+
+```ts
+const credential = await auth.getDriveCredential({
+  workspace: { type: "personal" },
 });
 
-const session = await auth.getSession();
-const organizations = await auth.listOrganizations();
-const acceptance = await auth.acceptInvitation({ invitationId });
+const authorization = `${credential.tokenType} ${credential.token}`;
+```
+
+For an organization workspace:
+
+```ts
 const credential = await auth.getDriveCredential({
-  workspace: { type: "organization", organizationId: organizations[0].id },
+  workspace: {
+    type: "organization",
+    organizationId: "org_01J8R7M6N5P4Q3S2T1",
+  },
+});
+```
+
+Drive credentials last about 14 minutes. Browser and device clients keep them in memory only and refresh them when two minutes remain. The server client does not cache them.
+
+If Drive rejects a credential, request a replacement:
+
+```ts
+const replacement = await auth.getDriveCredential({
+  workspace: { type: "personal" },
+  forceRefresh: true,
 });
-const signOut = await auth.signOut();
-const responseHeaders = new Headers();
-signOut.applyCookies(responseHeaders);
 ```
 
-The server client is request-scoped and does not cache credentials. Without `Authorization`, it forwards only reserved Better Auth cookies to Auth and never sends them to Drive. When the incoming request contains one valid, at-most-16-KiB `Bearer` authorization value, every Auth call forwards that exact header and omits all cookies; bearer authority always wins a mixed request. Server social ID-token sign-in therefore rejects locally with value-free `state_conflict` and makes no request when the incoming request has `Authorization`, rather than switching from bearer to newly minted cookie authority. Malformed or oversized authorization fails locally with value-free `authentication_required` and never falls back to a cookie. Apply cookies returned by server social sign-in, invitation acceptance, or sign-out to the outgoing response with the result's `applyCookies(headers)` method.
+The SDK does not replay the failed Drive request. Replay it only when the operation is safe to repeat.
 
-### Server-Owned Google Callback
+## Server And SSR
 
-HeyloMeet's existing BFF may retain ownership of Google authorization, state, PKCE, and callback handling. After its maintained OAuth client exchanges the code with Google, pass only the returned Google ID token and the original nonce to Auth. Auth independently verifies the token, returns a normalized authoritative Better Auth session plus cookies, and never redirects to Google or returns provider/session tokens to the browser:
+Create a server client inside each request handler. It forwards only Finueva Auth cookies. If the incoming request has a bearer token, that token takes precedence and the client forwards no cookies.
 
 ```ts
-const auth = createServerAuth({ authOrigin, appOrigin, request });
-const signedIn = await auth.signInWithSocialIdToken({
-  provider: "google",
-  idToken: googleTokenSet.id_token,
-  nonce: callbackNonce,
-  signUp: false,
+import { AuthError, createServerAuth } from "@finueva/auth/server";
+
+export async function handleAccountRequest(request: Request): Promise<Response> {
+  const auth = createServerAuth({
+    authOrigin: "https://auth.finueva.com",
+    appOrigin: "https://files.finueva.com",
+    request,
+  });
+
+  try {
+    const session = await auth.getSession();
+
+    if (!session) {
+      return Response.json(
+        { authenticated: false },
+        {
+          status: 401,
+          headers: { "cache-control": "no-store" },
+        },
+      );
+    }
+
+    return Response.json(
+      { user: session.user },
+      {
+        headers: { "cache-control": "no-store" },
+      },
+    );
+  } catch (error) {
+    if (error instanceof AuthError) {
+      return Response.json(
+        { code: error.code },
+        {
+          status: error.status,
+          headers: { "cache-control": "no-store" },
+        },
+      );
+    }
+
+    throw error;
+  }
+}
+```
+
+Some server mutations return cookies. Apply them to the outgoing response:
+
+```ts
+const result = await auth.signOut();
+const headers = new Headers({
+  "cache-control": "no-store",
+  location: "/signed-out",
 });
-const headers = new Headers({ location: "/" });
-signedIn.applyCookies(headers);
-return new Response(null, { status: 302, headers });
+
+result.applyCookies(headers);
+
+return new Response(null, { status: 303, headers });
 ```
 
-Set `signUp: true` only for an explicit product signup action. Do not put the Google ID token, Better Auth cookie, or Better Auth session token in the redirect URL, application cookie, logs, or page state. Do not forward Google access or refresh tokens to Auth.
+Call `applyCookies()` after server `signOut()`, `acceptInvitation()`, and `signInWithSocialIdToken()`. If you omit it, the browser does not receive the session change.
+
+Check `Origin`, Fetch Metadata, or a server-generated CSRF token before a server-side mutation. The SDK forwards authority; it does not replace your application's CSRF protection.
 
-## Device
+## CLI And Native Applications
+
+Use the device flow when a CLI or device can open a system browser:
 
 ```ts
-import { createDeviceAuth } from "@finueva/auth/device";
+import { AuthError, DeviceAuthorizationError, createDeviceAuth } from "@finueva/auth/device";
 
 const auth = createDeviceAuth({
   authOrigin: "https://auth.finueva.com",
   clientId: "finueva-cli",
 });
-if (auth._type !== "device") throw new Error("Expected a device Auth client");
-const authorization = await auth.requestAuthorization();
-showCode(authorization.userCode, authorization.verificationUri);
-const token = await auth.pollForToken(authorization, { signal });
-const session = await auth.getSession();
-await auth.signUpWithEmail(email, password, name); // direct first-party mobile flow
-await auth.signInWithEmail(email, password);
-await auth.signInWithSocialIdToken({ provider: "apple", idToken, nonce: rawNonce, signUp: false });
-await auth.updateProfile({ name, image });
-await auth.changePassword(currentPassword, newPassword);
-const credential = await auth.getDriveCredential({ workspace: { type: "personal" } });
-await auth.revokeCurrentDevice(); // or revokeAllSessions()
+
+const controller = new AbortController();
+process.once("SIGINT", () => controller.abort());
+
+try {
+  const authorization = await auth.requestAuthorization({
+    signal: controller.signal,
+  });
+
+  console.log(`Open ${authorization.verificationUriComplete}`);
+  console.log(`Code: ${authorization.userCode}`);
+
+  await auth.pollForToken(authorization, {
+    signal: controller.signal,
+  });
+
+  const session = await auth.getSession();
+  console.log(session ? `Signed in as ${session.user.email}` : "Not signed in");
+} catch (error) {
+  if (error instanceof DeviceAuthorizationError || error instanceof AuthError) {
+    console.error(error.code);
+  } else {
+    throw error;
+  }
+}
+```
+
+`clientId` is a public registered identifier, not a secret. Never display or log `authorization.deviceCode`.
+
+Device sessions are memory-only unless you provide `DeviceTokenPersistence`:
+
+```ts
+import { createDeviceAuth, type DeviceTokenPersistence } from "@finueva/auth/device";
+
+const persistence: DeviceTokenPersistence = {
+  read: (signal) => vault.read("finueva-auth", signal),
+  replace: (token, signal) => vault.replace("finueva-auth", token, signal),
+  delete: (signal) => vault.delete("finueva-auth", signal),
+};
+
+const auth = createDeviceAuth({
+  authOrigin: "https://auth.finueva.com",
+  clientId: "finueva-desktop",
+  fetch: nativeFetch,
+  persistence,
+});
 ```
 
-Polling starts at the server-provided interval, adds five seconds after each RFC 8628 `slow_down`, has no transport retry, and stops on denial, expiry, cancellation, the configured `maxPollingMs`, malformed/bounded responses, or transport timeout. A bounded access token recoverable from otherwise malformed redemption metadata is best-effort revoked and no local authority is retained. The only requested scope is `openid`.
+Use the operating system's credential vault. `replace()` must replace the complete token atomically. Do not use local storage, a WebView cookie jar, or a plaintext file. A native application must also supply a reviewed native HTTPS transport that omits ambient WebView cookies.
 
-The token is memory-only by default. Secure persistence is opt-in through a structural adapter implementing `read`, atomic `replace`, and `delete`; every operation receives an `AbortSignal`. The SDK serializes polling, account changes, expiry synchronization, and revocation, including persistence calls. Malformed non-null persisted authority is best-effort deleted before hydration fails, allowing a later process to start without the bad value. The caller owns encryption and platform credential storage. Adapter and authority failures are value-free and never include device codes or tokens. This export uses standard expiring/revocable Better Auth sessions and does not implement refresh tokens.
+Direct first-party native email sign-in is available to registered applications:
 
-Browser and device clients expose the literal `_type` values `"browser"` and `"device"`. Use that discriminant to narrow a union before invoking runtime-specific methods; do not infer the client type from environment globals.
+```ts
+const session = await auth.signInWithEmail("ada@example.com", "correct-horse-battery-staple");
+```
+
+End the current device session with `revokeCurrentDevice()`. End every browser and device session for the account with `revokeAllSessions()`.
+
+## Social ID Tokens
+
+Browser, server, and device clients accept Google and Apple ID tokens from a first-party provider integration:
+
+```ts
+const session = await auth.signInWithSocialIdToken({
+  provider: "google",
+  idToken,
+  nonce,
+  signUp: false,
+});
+```
+
+Set `signUp: true` only after the user chooses to create an account. The application owns the provider authorization flow, state, nonce, and PKCE transaction. Pass only the ID token to Auth. Do not pass provider access or refresh tokens.
 
-Direct email and social signup/sign-in are intended for registered first-party mobile or Tauri clients. The SDK verifies the opaque token through bearer `get-session`, derives its expiry from that authoritative session, atomically replaces secure persistence, and only then publishes it in memory. Verification or replacement failure triggers best-effort revocation of the new session and retains the previous token only after current authority verifies it. A successful account switch best-effort revokes the replaced current-device session after publishing the new token. Password replacement follows the same rule; when Better Auth returns no replacement token, the current token is retained only after an authoritative session check. `getSession()` synchronizes changed authoritative expiry back to persistence.
+The generic Google and Apple redirect flow is not exposed by this package.
 
-For Tauri, implement `DeviceTokenPersistence` in Rust commands backed by the operating system credential vault (Keychain, Credential Manager, or Secret Service). Store the complete `DeviceToken` as one encrypted/versioned item, make replacement atomic, and restrict access to this application identity. An `AbortSignal` cannot cancel a native `invoke` that has already been dispatched. The SDK retains an internal persistence queue after public timeout, runs compensating deletion after a late replacement, and rejects later authority operations with `state_conflict` until that queue settles. The process can still terminate between a native commit and compensation; production adapters need a native pending-operation journal or equivalent startup cleanup before returning a stored token. This process-crash recovery remains outside SDK qualification. Do not use WebView local storage, a plaintext file, Tauri Store, logs, crash metadata, or frontend state. Drive credentials remain memory-only even when the Better Auth session uses secure OS persistence; the device client keeps only one selected workspace credential and renews it with two minutes remaining. It permits at most one issuance request: an exact same-workspace non-forced call may share that request, while a workspace switch or forced refresh returns `state_conflict` until it settles.
+## Errors
+
+Invalid local arguments throw `TypeError`. Auth failures throw `AuthError`:
+
+```ts
+try {
+  await auth.getSession();
+} catch (error) {
+  if (!(error instanceof AuthError)) throw error;
+
+  if (error.code === "auth_request_rate_limited") {
+    scheduleRetry(error.retryAfterSeconds ?? 60);
+  } else if (error.code === "identity_authority_unavailable") {
+    showAuthUnavailable();
+  } else {
+    showAuthError(error.code);
+  }
+}
+```
 
-Tauri must also supply `createDeviceAuth({ fetch })` with a native HTTP adapter or move the complete Auth transport into Rust. Native Google or Apple authorization submits the provider ID token through `signInWithSocialIdToken`; the adapter must emit neither WebView cookies nor a WebView `Origin`, and every device SDK request uses `credentials: "omit"`. The default WebView fetch path is unsupported for `tauri://` applications and environments that send `Origin: null`. Device authorization remains available by opening `verificationUriComplete` in the system browser.
+Use `error.code` for application behavior. Do not parse `error.message`.
+
+| Code                             | What the application should do                                        |
+| -------------------------------- | --------------------------------------------------------------------- |
+| `invalid_credentials`            | Ask the user to check the credential.                                 |
+| `invalid_auth_input`             | Correct the account input.                                            |
+| `account_conflict`               | Stop the account action. Do not expose account-existence details.     |
+| `authentication_required`        | Start sign-in.                                                        |
+| `email_verification_required`    | Ask the user to verify the current email.                             |
+| `invitation_unavailable`         | Ask for a new invitation. Do not retry the old one.                   |
+| `invalid_workspace_selection`    | Send one exact personal or organization workspace.                    |
+| `state_conflict`                 | Wait for the active authority operation, then read the session again. |
+| `access_denied`                  | Stop the operation.                                                   |
+| `credential_rate_limited`        | Wait for `retryAfterSeconds` when present.                            |
+| `auth_request_rate_limited`      | Wait for `retryAfterSeconds` when present.                            |
+| `identity_authority_unavailable` | Keep state unverified and try again later.                            |
+
+Device authorization can also throw `DeviceAuthorizationError`. Its codes are `device_access_denied`, `device_authorization_cancelled`, `device_code_expired`, `invalid_device_authorization`, and `identity_authority_unavailable`.
+
+The SDK does not automatically retry requests.
+
+## Security Notes
+
+- Use HTTPS. Plain HTTP is accepted only on localhost.
+- Use exact registered origins. Do not build an Auth origin from the current request host.
+- Keep browser session snapshots display-only.
+- Create server clients per request. Do not keep one in a module singleton.
+- Apply returned cookies before sending a server response.
+- Keep device bearer tokens in an operating-system credential vault.
+- Keep Drive credentials in memory and send them only to Drive.
+- Do not log cookies, bearer tokens, ID tokens, reset tokens, device codes, or complete Auth responses.
+- Protect application mutations against CSRF before calling the server client.
 
 ## Current Limits
 
-- Organization mutation and active-organization state are not exposed; callers select an organization returned by `listOrganizations()` explicitly.
-- Cross-root SSO is not implemented.
-- Cross-root redirect SSO and generic Better Auth Google/Apple social redirects are unsupported; an application or native provider SDK must obtain the ID token.
-- Apple first signup without a verified signed email is unsupported. Requests with caller-supplied Apple email/name fields are rejected; a later email-less token works only for an already-linked Apple subject with a current verified Auth email.
-- The package does not persist Drive credentials or expose Better Auth or Unstorage internals.
-- Account deletion is intentionally not exposed by browser, server, or device exports.
-- Public errors are `AuthError` instances with stable, value-free codes.
-- Organization contexts with more than 50 current teams fail with `organization_context_too_large` and status `422`.
+- The public API is experimental and can change before `1.0.0`.
+- Requests time out after 10 seconds by default. `timeoutMs` accepts 1 to 60,000 milliseconds.
+- Auth JSON responses are limited to 64 KiB.
+- Browser snapshots and bearer authorization values are limited to 16 KiB.
+- Organization lists fail closed at 100 records.
+- Organization Drive context supports at most 50 current teams.
+- Account deletion and organization management are not exposed.
+- Cross-root SSO and custom refresh tokens are not implemented.
+- Hosted mobile transport and operating-system vault qualification are incomplete.
+- Production support gates are not complete.

package/dist/device.d.ts

@@ -1,4 +1,4 @@
-import { C as AuthErrorStatus, S as AuthErrorCode, _ as SocialIdTokenInput, l as DriveCredential, o as AuthSession, u as DriveCredentialInput, v as SocialIdTokenProvider, x as AuthError, y as UpdateProfileInput } from "./types-DDopQNZR.js";
+import { A as UpdateProfileInput, M as AuthError, N as AuthErrorCode, O as SocialIdTokenInput, P as AuthErrorStatus, T as ReceivedOrganizationInvitationPage, _ as OrganizationPage, b as OrganizationTeamMemberPage, g as OrganizationMemberPage, h as OrganizationMember, k as SocialIdTokenProvider, l as DriveCredential, m as OrganizationInvitationPage, o as AuthSession, p as OrganizationInvitation, r as AuthOrganization, u as DriveCredentialInput, v as OrganizationPageInput, w as ReceivedOrganizationInvitation, x as OrganizationTeamPage, y as OrganizationTeam } from "./types-B67VIvTQ.js";
 //#region src/device.d.ts
 type DeviceAuthorizationErrorCode = "device_access_denied" | "device_authorization_cancelled" | "device_code_expired" | "invalid_device_authorization" | "identity_authority_unavailable";
 declare class DeviceAuthorizationError extends Error {
@@ -43,6 +43,15 @@ interface DeviceAuthClient {
   }): Promise<DeviceAuthorization>;
   pollForToken(authorization: DeviceAuthorization, options?: PollDeviceOptions): Promise<DeviceToken>;
   getSession(): Promise<AuthSession | null>;
+  listOrganizations(input?: OrganizationPageInput): Promise<OrganizationPage>;
+  getOrganization(organizationId: string): Promise<AuthOrganization>;
+  listOrganizationMembers(organizationId: string, input?: OrganizationPageInput): Promise<OrganizationMemberPage>;
+  listOrganizationTeams(organizationId: string, input?: OrganizationPageInput): Promise<OrganizationTeamPage>;
+  listOrganizationTeamMembers(organizationId: string, teamId: string, input?: OrganizationPageInput): Promise<OrganizationTeamMemberPage>;
+  listOrganizationInvitations(organizationId: string, input?: OrganizationPageInput): Promise<OrganizationInvitationPage>;
+  getOrganizationInvitation(organizationId: string, invitationId: string): Promise<OrganizationInvitation>;
+  listReceivedInvitations(input?: OrganizationPageInput): Promise<ReceivedOrganizationInvitationPage>;
+  getReceivedInvitation(invitationId: string): Promise<ReceivedOrganizationInvitation>;
   getToken(): Promise<DeviceToken | null>;
   signUpWithEmail(email: string, password: string, name: string): Promise<AuthSession>;
   signInWithEmail(email: string, password: string): Promise<AuthSession>;
@@ -55,4 +64,4 @@ interface DeviceAuthClient {
 }
 declare function createDeviceAuth(options: DeviceAuthOptions): DeviceAuthClient;
 //#endregion
-export { AuthError, type AuthErrorCode, type AuthErrorStatus, DeviceAuthClient, DeviceAuthOptions, DeviceAuthorization, DeviceAuthorizationError, DeviceAuthorizationErrorCode, DeviceToken, DeviceTokenPersistence, PollDeviceOptions, type SocialIdTokenInput, type SocialIdTokenProvider, createDeviceAuth };
+export { AuthError, type AuthErrorCode, type AuthErrorStatus, type AuthOrganization, DeviceAuthClient, DeviceAuthOptions, DeviceAuthorization, DeviceAuthorizationError, DeviceAuthorizationErrorCode, DeviceToken, DeviceTokenPersistence, type OrganizationInvitation, type OrganizationInvitationPage, type OrganizationMember, type OrganizationMemberPage, type OrganizationPage, type OrganizationPageInput, type OrganizationTeam, type OrganizationTeamMemberPage, type OrganizationTeamPage, PollDeviceOptions, type ReceivedOrganizationInvitation, type ReceivedOrganizationInvitationPage, type SocialIdTokenInput, type SocialIdTokenProvider, createDeviceAuth };