@finueva/auth 0.10.0 → 0.11.0

package/README.md

@@ -1,19 +1,10 @@
-# `@finueva/auth`
+# Finueva Auth SDK for TypeScript
 
-The official TypeScript client for Finueva Auth.
+Use `@finueva/auth` to add Finueva sign-in, organization access, invitations, and Drive credentials to a browser, server, CLI, or native application.
 
-Use it to:
+The current published version is `0.10.1`. The package is ESM-only. Node.js consumers require Node.js 22 or later. Other server runtimes must provide compatible Fetch, Web Crypto, URL, and Web Streams APIs. Its interface is Experimental until version `1.0.0`.
 
-- sign users in with email and password;
-- read the current session;
-- manage profile and password details;
-- read organizations, create ordinary teams, replace display data, 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`.
-
-Sections marked **Unreleased** describe repository source and are not available in the currently published `@finueva/auth@0.9.0` package.
+The passkey and recent-authentication methods below describe this repository's next package candidate. Published version `0.10.1` does not include them.
 
 ## Install
 
@@ -21,22 +12,30 @@ Sections marked **Unreleased** describe repository source and are not available
 pnpm add @finueva/auth
 ```
 
-Node.js applications require Node.js 22 or later.
+For a browser or server application, ask your Auth operator for:
+
+- the Auth origin for your environment;
+- your registered application origin.
 
-## Pick The Right Client
+For a CLI or native application, ask for:
 
-| 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              |
+- the Auth origin for your environment;
+- a registered device client ID.
 
-Create one browser client for the application, one server client per request, or one device client per application process.
+Do not reuse configuration from another application or environment.
 
-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.
+## Choose A Client
+
+| Runtime                   | Import                 | Session authority              | Create it                |
+| ------------------------- | ---------------------- | ------------------------------ | ------------------------ |
+| Browser                   | `@finueva/auth`        | Auth HTTP-only cookie          | Once for the application |
+| Server or SSR handler     | `@finueva/auth/server` | Incoming Auth cookie or bearer | Once per request         |
+| CLI or native application | `@finueva/auth/device` | Device bearer session          | Once per process         |
 
 ## Browser Quick Start
 
+Create the client with the exact Auth and application origins:
+
 ```ts
 import { AuthError, createAuthClient } from "@finueva/auth";
 
@@ -44,189 +43,62 @@ const auth = createAuthClient({
   authOrigin: "https://auth.finueva.com",
   appOrigin: window.location.origin,
 });
+```
+
+Read the current session:
 
+```ts
 const session = await auth.getSession();
 
 if (session) {
   console.log(`Signed in as ${session.user.email}`);
-} else {
-  console.log("Not signed in");
 }
+```
+
+Sign in with email and password:
 
+```ts
 try {
-  const nextSession = await auth.signIn({
+  const session = await auth.signIn({
     email: "ada@example.com",
     password: "correct-horse-battery-staple",
   });
 
-  console.log(`Welcome ${nextSession.user.name}`);
+  console.log(`Welcome ${session.user.name}`);
 } catch (error) {
   if (error instanceof AuthError && error.code === "invalid_credentials") {
-    console.log("Check the email and password.");
+    showInvalidCredentials();
   } 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) => {
-  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;
-  }
-});
-
-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,
-});
-```
-
-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",
-});
-```
-
-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`,
-});
-```
-
-The callback must use the application's exact origin. Omit it to use the default Auth result page.
-
-### List Organizations
-
-```ts
-let page = await auth.listOrganizations({ limit: 50 });
-
-for (const organization of page.organizations) {
-  console.log(organization.id, organization.name, organization.slug);
-}
-
-if (page.nextCursor) {
-  page = await auth.listOrganizations({ limit: 50, cursor: page.nextCursor });
-}
-```
-
-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()`.
-
-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.
-
-### Create A Team
-
-**Unreleased:** this method will ship in a later package version and is not in `@finueva/auth@0.9.0`.
-
-```ts
-const idempotencyKey = crypto.randomUUID();
-const team = await auth.createOrganizationTeam("org_01J8R7M6N5P4Q3S2T1", "Platform Engineering", idempotencyKey);
-```
+The browser owns the session cookie. The SDK does not expose or persist it.
 
-The name and caller-owned idempotency key must each contain from 1 through 255 UTF-8 bytes. Use a
-new key for each intended team. If a response is lost, send the same organization ID, name, and key
-again. Auth returns the original creation result for a completed same-key request, even if a later
-operation changed the team display. A conflicting or unresolved same-key request returns
-`state_conflict`. The SDK never retries automatically.
+## Common Tasks
 
-For an ordinary organization, a current effective owner or administrator can use the cookie or
-bearer lane. For a managed organization, a current manual owner or manual administrator must use the
-cookie lane. The method creates only an ordinary team.
+| Task                          | Browser                                     | Server                                 | Device                                 |
+| ----------------------------- | ------------------------------------------- | -------------------------------------- | -------------------------------------- |
+| Create an account             | `signUp()`                                  | Not available                          | `signUpWithEmail()`                    |
+| Read the current session      | `getSession()`                              | `getSession()`                         | `getSession()`                         |
+| Observe session state         | `onAuthStateChange()`                       | Not available                          | Not available                          |
+| Update a profile              | `updateProfile()`                           | Not available                          | `updateProfile()`                      |
+| Change a password             | `changePassword()`                          | Not available                          | `changePassword()`                     |
+| Reset a password              | `requestPasswordReset()`, `resetPassword()` | Not available                          | Not available                          |
+| Verify an email               | `sendVerificationEmail()`                   | Not available                          | Not available                          |
+| List organizations            | `listOrganizations()`                       | `listOrganizations()`                  | `listOrganizations()`                  |
+| Create an ordinary team       | `createOrganizationTeam()`                  | `createOrganizationTeam()`             | `createOrganizationTeam()`             |
+| Invite an ordinary member     | `createOrganizationMemberInvitation()`      | `createOrganizationMemberInvitation()` | `createOrganizationMemberInvitation()` |
+| Accept an invitation          | `acceptInvitation()`                        | `acceptInvitation()`                   | Not available                          |
+| Enroll a passkey              | `addPasskey()`                              | Not available                          | Not available                          |
+| Perform recent authentication | Three `*RecentAuthentication*()` methods    | Not available                          | Not available                          |
+| Request Drive access          | `getDriveCredential()`                      | `getDriveCredential()`                 | `getDriveCredential()`                 |
+| End the current session       | `signOut()`                                 | `signOut()`                            | `revokeCurrentDevice()`                |
 
-### Create A Member Invitation
+## Create An Organization Invitation
 
-**Unreleased:** this method will ship in a later package version and is not in `@finueva/auth@0.9.0`.
+Use one new idempotency key for each invitation that you intend to create:
 
 ```ts
 const invitation = await auth.createOrganizationMemberInvitation("org_01J8R7M6N5P4Q3S2T1", {
@@ -238,68 +110,54 @@ const invitation = await auth.createOrganizationMemberInvitation("org_01J8R7M6N5
 console.log(invitation.id, invitation.expiresAt);
 ```
 
-The SDK trims and lowercases the email address. The email address can contain no more than 320 UTF-8 bytes. `teamIds` is optional and can contain no more than 100 unique ordinary team IDs. The caller-owned idempotency key must contain from 1 through 255 UTF-8 bytes.
-
-Use a new key for each intended invitation. If a response is lost, send the same organization ID and input again. The method returns only the invitation ID and expiry. It does not report email delivery. The SDK never retries automatically.
-
-For an ordinary organization, a current effective owner or administrator can use the cookie or bearer lane. Managed organizations are denied.
-
-### Accept An Invitation
-
-```ts
-const result = await auth.acceptInvitation({
-  invitationId: "invitation_01J8R7M6N5P4Q3S2T1",
-});
+If the response is lost, repeat the same request with the same key. The SDK does not retry automatically. The result confirms invitation creation. It does not confirm email delivery.
 
-console.log(result.organizationId);
-```
+## Perform Recent Authentication
 
-### Replace Organization Display
+The experimental passkey methods run only when the browser page uses the exact Auth Origin. To enroll a passkey, first create a new password-authenticated session on that origin:
 
 ```ts
-const display = await auth.updateOrganizationDisplay("org_01J8R7M6N5P4Q3S2T1", {
-  name: "Example Group",
-  slug: "example-group",
-  logo: null,
-});
+await auth.signIn({ email, password });
+await auth.addPasskey();
 ```
 
-Send all three fields. `name` and `slug` can contain no more than 255 UTF-8 bytes. Use `logo: null` to remove the logo. A non-null logo must be an exact canonical HTTPS URL of no more than 2048 UTF-8 bytes. The method supports manual owners and manual administrators of ordinary organizations. Provider-only administrators are denied. It does not update metadata, lifecycle, membership, teams, invitations, or active-organization state.
-
-Browser and cookie-based server calls require the exact configured application Origin. The SDK reports a denied or missing Origin as `request_origin_denied`. Other organization authority denials use `access_denied`.
+The enrollment authorization expires after five minutes. It is single-use. Signup, social sign-in, session refresh, bearer use, and generic session creation do not authorize enrollment. A User without a fresh password sign-in cannot use this path.
 
-The method does not retry. If a response is lost, submit the same complete desired state again. Concurrent different updates use last-write-wins behavior.
-
-### Replace Team Display
-
-**Unreleased:** this method will ship in a later package version and is not in `@finueva/auth@0.9.0`.
+Start one reviewed platform-role action before invoking passkey authentication:
 
 ```ts
-const display = await auth.updateOrganizationTeamDisplay("org_01J8R7M6N5P4Q3S2T1", "team_01J8R7M6N5P4Q3S2T1", {
-  name: "Platform Engineering",
+await auth.startPlatformRoleChangeRecentAuthentication({
+  targetUserId: "user_01J8R7M6N5P4Q3S2T1",
+  requestedRoles: ["administrator", "investigator"],
+  expectedRevision: 4,
 });
-```
 
-Send the complete `name`. It can contain no more than 255 UTF-8 bytes. For an ordinary organization, a current effective owner or administrator can use the cookie or bearer lane. For a managed organization, a current manual owner or manual administrator must use the cookie lane. Managed teams are denied.
+await auth.verifyRecentAuthenticationWithPasskey();
 
-The method does not retry. If a response is lost, submit the same complete desired name again. Concurrent different updates use last-write-wins behavior.
+const continuation = await auth.getRecentAuthenticationStatus();
+if (continuation.status === "ready") {
+  showReviewedActionIsReady();
+}
+```
 
-### Sign Out
+The maintained passkey client performs the WebAuthn ceremony for the pending action when a compatible authenticator is present. Auth binds the exact generated challenge to that action. The SDK returns only `pending` or `ready`. It does not expose the challenge, WebAuthn response, session, cookies, proof, or hashes. `ready` does not grant a platform role or reusable administration mode. The tracer has no proof-consumption API. A future exact mutation must add atomic one-use consumption with its state change. No platform mutation is currently implemented.
 
-```ts
-await auth.signOut();
-```
+If a start result is unavailable, call `startPlatformRoleChangeRecentAuthentication()` again with the same normalized input. The client reuses the current request nonce. A different start or observed account transition removes this local retry state. Only one start request can be active. An overlapping call returns `state_conflict` before network I/O. The SDK does not retry automatically.
 
 ## Request A Drive Credential
 
-Ask Auth for a credential for one workspace:
+Request one short-lived credential for one workspace:
 
 ```ts
 const credential = await auth.getDriveCredential({
   workspace: { type: "personal" },
 });
 
-const authorization = `${credential.tokenType} ${credential.token}`;
+await fetch("https://drive.finueva.com/api/files", {
+  headers: {
+    authorization: `${credential.tokenType} ${credential.token}`,
+  },
+});
 ```
 
 For an organization workspace:
@@ -313,184 +171,87 @@ const credential = await auth.getDriveCredential({
 });
 ```
 
-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,
-});
-```
-
-The SDK does not replay the failed Drive request. Replay it only when the operation is safe to repeat.
+Browser and device clients cache one completed credential in memory. The server client does not cache credentials. The SDK never replays a failed Drive operation.
 
-## Server And SSR
+## Server Quick Start
 
-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.
+Create one client inside each request handler:
 
 ```ts
-import { AuthError, createServerAuth } from "@finueva/auth/server";
+import { createServerAuth } from "@finueva/auth/server";
 
-export async function handleAccountRequest(request: Request): Promise<Response> {
+export async function handleRequest(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" },
-        },
-      );
-    }
+  const session = await auth.getSession();
 
-    throw error;
-  }
+  return Response.json(
+    { authenticated: session !== null, user: session?.user ?? null },
+    { headers: { "cache-control": "no-store" } },
+  );
 }
 ```
 
-Some server mutations return cookies. Apply them to the outgoing response:
+If the incoming request has `Authorization`, the server client uses that bearer and forwards no cookies. Otherwise, it forwards only Auth cookies.
+
+Some server methods return cookie changes. Apply them before you send the response:
 
 ```ts
 const result = await auth.signOut();
-const headers = new Headers({
-  "cache-control": "no-store",
-  location: "/signed-out",
-});
+const headers = new Headers({ location: "/signed-out" });
 
 result.applyCookies(headers);
 
 return new Response(null, { status: 303, headers });
 ```
 
-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.
+Call `applyCookies()` after server `signOut()`, `acceptInvitation()`, and `signInWithSocialIdToken()`.
 
-## CLI And Native Applications
+## Device Quick Start
 
-Use the device flow when a CLI or device can open a system browser:
+Use the device flow for a CLI or native application that can open a system browser:
 
 ```ts
-import { AuthError, DeviceAuthorizationError, createDeviceAuth } from "@finueva/auth/device";
+import { createDeviceAuth } from "@finueva/auth/device";
 
 const auth = createDeviceAuth({
   authOrigin: "https://auth.finueva.com",
   clientId: "finueva-cli",
 });
 
-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 authorization = await auth.requestAuthorization();
 
-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),
-};
+console.log(`Open ${authorization.verificationUriComplete}`);
+console.log(`Code: ${authorization.userCode}`);
 
-const auth = createDeviceAuth({
-  authOrigin: "https://auth.finueva.com",
-  clientId: "finueva-desktop",
-  fetch: nativeFetch,
-  persistence,
-});
+await auth.pollForToken(authorization);
 ```
 
-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.
-
-Direct first-party native email sign-in is available to registered applications:
-
-```ts
-const session = await auth.signInWithEmail("ada@example.com", "correct-horse-battery-staple");
-```
+`clientId` is public. `deviceCode` is not. Never log or display the device code.
 
-End the current device session with `revokeCurrentDevice()`. End every browser and device session for the account with `revokeAllSessions()`.
+Device tokens are memory-only by default. For persistence, supply a `DeviceTokenPersistence` adapter backed by an operating-system credential vault. Do not use local storage, a WebView cookie jar, or a plaintext file.
 
-## Social ID Tokens
+## Handle Errors
 
-Browser, server, and device clients accept Google and Apple ID tokens from a first-party provider integration:
+Constructor and selected account-input errors can throw `TypeError`. Validated SDK request failures throw `AuthError`. Device authorization can throw `DeviceAuthorizationError`:
 
 ```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.
+import { AuthError } from "@finueva/auth";
 
-The generic Google and Apple redirect flow is not exposed by this package.
-
-## Errors
-
-Invalid local arguments throw `TypeError`. Auth failures throw `AuthError`:
-
-```ts
 try {
-  await auth.getSession();
+  await auth.signIn({
+    email: "ada@example.com",
+    password: "correct-horse-battery-staple",
+  });
 } catch (error) {
   if (!(error instanceof AuthError)) throw error;
 
-  if (error.code === "auth_request_rate_limited") {
-    scheduleRetry(error.retryAfterSeconds ?? 60);
+  if (error.code === "invalid_credentials") {
+    showInvalidCredentials();
   } else if (error.code === "identity_authority_unavailable") {
     showAuthUnavailable();
   } else {
@@ -499,48 +260,55 @@ try {
 }
 ```
 
-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.
+Use `error.code` for application behavior. Do not parse `error.message`. Except for RFC 8628 device polling, the SDK does not automatically repeat requests.
 
-## Security Notes
+## Security Checklist
 
 - Use HTTPS. Plain HTTP is accepted only on localhost.
-- Use exact registered origins. Do not build an Auth origin from the current request host.
+- Register exact application origins.
+- Create server clients per request.
+- Apply returned server cookies before you send the response.
 - 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.
+- Keep device sessions in an operating-system credential vault.
+- Keep Drive credentials in memory.
+- Protect server-side mutations against CSRF.
 - 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
 
-- 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.
+- The package is Experimental until `1.0.0`.
+- Requests time out after 10 seconds by default.
+- `timeoutMs` accepts 1 through 60,000 milliseconds.
+- Most responses are limited to 64 KiB. Organization read responses can use up to 256 KiB.
 - Browser snapshots and bearer authorization values are limited to 16 KiB.
-- Organization lists fail closed at 100 records.
+- Organization collections use page sizes from 1 through 100.
 - Organization Drive context supports at most 50 current teams.
-- Ordinary-organization display replacement is the only organization mutation in `@finueva/auth@0.9.0`. Unreleased source also exposes ordinary-team creation and display replacement. Account deletion and other 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.
+- Invitation creation supports only the `member` role in ordinary organizations.
+- Invitation resend and cancellation are not public SDK methods.
+- Cross-root SSO, custom refresh tokens, and account deletion are not implemented.
+- Production support gates are incomplete. Ask the Auth operator for the current environment status before adoption.
+
+## Package Exports
+
+```ts
+import { AuthError, createAuthClient } from "@finueva/auth";
+import { createServerAuth } from "@finueva/auth/server";
+import { DeviceAuthorizationError, createDeviceAuth } from "@finueva/auth/device";
+```
+
+TypeScript declarations ship with the package. The public declarations do not expose Better Auth types.
+
+## Documentation
+
+Long-form task guides are maintained with the Auth source:
+
+- [Get started](https://github.com/Ifkafin/auth/blob/main/apps/developer/docs/sdk/index.md)
+- [Browser applications](https://github.com/Ifkafin/auth/blob/main/apps/developer/docs/sdk/browser.md)
+- [Server and SSR applications](https://github.com/Ifkafin/auth/blob/main/apps/developer/docs/sdk/server.md)
+- [CLI and native applications](https://github.com/Ifkafin/auth/blob/main/apps/developer/docs/sdk/device.md)
+- [Social ID-token sign-in](https://github.com/Ifkafin/auth/blob/main/apps/developer/docs/sdk/social-sign-in.md)
+- [Organizations and invitations](https://github.com/Ifkafin/auth/blob/main/apps/developer/docs/sdk/organizations.md)
+- [Drive credentials](https://github.com/Ifkafin/auth/blob/main/apps/developer/docs/sdk/drive-credentials.md)
+- [Errors and recovery](https://github.com/Ifkafin/auth/blob/main/apps/developer/docs/sdk/errors-and-recovery.md)
+
+These links track current source and can describe a newer SDK version. Check the version at the start of the guide. Repository access is required until these guides have a public, versioned documentation deployment.