@finueva/auth 0.3.0 → 0.5.0

package/README.md

@@ -23,6 +23,10 @@ const stop = auth.onAuthStateChange((state) => {
 
 const session = await auth.getSession();
 await auth.signIn({ email, password });
+await auth.sendVerificationEmail({
+  email,
+  callbackURL: `${window.location.origin}/account/email-verified`,
+});
 const organizations = await auth.listOrganizations();
 const acceptance = await auth.acceptInvitation({ invitationId });
 const credential = await auth.getDriveCredential({
@@ -37,6 +41,8 @@ stop();
 
 The Auth session uses the Auth-owned HTTP-only cookie. `getSession()` and `onSessionChange()` report Better Auth authority results only. `onAuthStateChange()` separately emits `loading`, non-authoritative `cached`, authoritative `authenticated`/`unauthenticated`, or non-authoritative `unavailable`; it verifies every cache hint immediately.
 
+`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.
+
 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.
 
 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.
@@ -64,14 +70,37 @@ const acceptance = await auth.acceptInvitation({ invitationId });
 const credential = await auth.getDriveCredential({
   workspace: { type: "organization", organizationId: organizations[0].id },
 });
+const signOut = await auth.signOut();
+const responseHeaders = new Headers();
+signOut.applyCookies(responseHeaders);
+```
+
+The server client is request-scoped and does not cache credentials. It forwards only reserved Better Auth cookies to Auth and never sends them to Drive. Apply cookies returned by server invitation acceptance or sign-out to the outgoing response with `acceptance.applyCookies(headers)` or `signOut.applyCookies(headers)`.
+
+## Device
+
+```ts
+import { createDeviceAuth } from "@finueva/auth/device";
+
+const auth = createDeviceAuth({
+  authOrigin: "https://auth.finueva.com",
+  clientId: "finueva-cli",
+});
+const authorization = await auth.requestAuthorization();
+showCode(authorization.userCode, authorization.verificationUri);
+const token = await auth.pollForToken(authorization, { signal });
+const session = await auth.getSession();
+await auth.revokeCurrentDevice(); // or revokeAllSessions()
 ```
 
-The server client is request-scoped and does not cache credentials. It forwards the incoming Auth cookie only to Auth and never sends it to Drive. Apply cookies returned by server invitation acceptance to the outgoing response with `acceptance.applyCookies(headers)`.
+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. The only requested scope is `openid`.
+
+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` and must stop without committing when aborted. 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.
 
 ## Current Limits
 
 - Organization mutation and active-organization state are not exposed; callers select an organization returned by `listOrganizations()` explicitly.
-- Cross-root SSO is not part of `0.1.0`.
+- Cross-root SSO is not implemented.
 - The package does not persist Drive credentials or expose Better Auth or Unstorage internals.
 - 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`.

package/dist/device.d.ts

@@ -0,0 +1,51 @@
+import { o as AuthSession } from "./types-HSdjQWMZ.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 {
+  readonly code: DeviceAuthorizationErrorCode;
+  constructor(code: DeviceAuthorizationErrorCode);
+}
+interface DeviceToken {
+  accessToken: string;
+  tokenType: "Bearer";
+  expiresAt: Date;
+  scope: "openid";
+}
+interface DeviceTokenPersistence {
+  read(signal: AbortSignal): DeviceToken | null | Promise<DeviceToken | null>;
+  replace(token: DeviceToken, signal: AbortSignal): void | Promise<void>;
+  delete(signal: AbortSignal): void | Promise<void>;
+}
+interface DeviceAuthorization {
+  deviceCode: string;
+  userCode: string;
+  verificationUri: string;
+  verificationUriComplete: string;
+  expiresAt: Date;
+  intervalSeconds: number;
+}
+interface DeviceAuthOptions {
+  authOrigin: string;
+  clientId: string;
+  fetch?: typeof globalThis.fetch;
+  now?: () => number;
+  persistence?: DeviceTokenPersistence;
+  timeoutMs?: number;
+  maxPollingMs?: number;
+}
+interface PollDeviceOptions {
+  signal?: AbortSignal;
+}
+interface DeviceAuthClient {
+  requestAuthorization(options?: {
+    signal?: AbortSignal;
+  }): Promise<DeviceAuthorization>;
+  pollForToken(authorization: DeviceAuthorization, options?: PollDeviceOptions): Promise<DeviceToken>;
+  getSession(): Promise<AuthSession | null>;
+  getToken(): Promise<DeviceToken | null>;
+  revokeCurrentDevice(): Promise<void>;
+  revokeAllSessions(): Promise<void>;
+}
+declare function createDeviceAuth(options: DeviceAuthOptions): DeviceAuthClient;
+//#endregion
+export { DeviceAuthClient, DeviceAuthOptions, DeviceAuthorization, DeviceAuthorizationError, DeviceAuthorizationErrorCode, DeviceToken, DeviceTokenPersistence, PollDeviceOptions, createDeviceAuth };