@foir/sdk 0.20.0 → 0.22.0

package/dist/auth/auth.d.ts

@@ -1,11 +1,12 @@
 /**
- * Foir customer auth — framework-agnostic flows, token lifecycle, and guards.
+ * Foir sign-in for your app's users: framework-agnostic flows, token
+ * lifecycle, and guards.
  *
  * Session I/O is injected via {@link SessionAdapter} (no Hydrogen/React-Router
  * coupling). Pre-login flows authenticate with the project `x-api-key`;
- * post-login reads add the customer bearer. The project-specific profile (e.g.
- * `isAdmin`) is resolved by a consumer-supplied `resolveUser` — the SDK never
- * hardcodes the per-project customer profile shape.
+ * post-login reads add the user's bearer. Anything project-specific about the
+ * user (a profile record, say) is resolved by a consumer-supplied
+ * `resolveUser`: the SDK never hardcodes a per-project profile shape.
  *
  * TRANSPORT. Every flow below addresses the server's generated `auth` namespace
  * through `./ops`, which is `@foir/sdk/data`'s op transport. This module holds
@@ -16,23 +17,17 @@
  */
 import { type FoirEnv } from '../graphql/foir-request';
 import { type AuthOpName, type AuthOpOptions } from './ops';
-import { type AuthConfig, type AuthProviderPublic, type CurrentUser, type CustomerAuthResult, type DefaultAuthProvider, type DeleteAccountResult, type MyOrganization, type SelectedOrganization, type ProviderCallbackInput, type ProviderLoginInput, type ProviderLoginResult, type ProviderOTPVerifyInput, type ProviderToken, type SignupContext, type WaitlistJoinResult } from './operations';
+import { type AuthConfig, type AuthProviderPublic, type CurrentUser, type AuthResult, type DefaultAuthProvider, type AuthorizedApp, type DeleteAccountResult, type MyOrganization, type MyProfile, type MyProfileChange, type MySession, type MyFactor, type StepUp, type FactorEnrollment, type MySignInMethod, type NewPersonalAccessToken, type ProviderCallbackInput, type ProviderLoginInput, type ProviderLoginResult, type ProviderOTPVerifyInput, type ProviderToken, type SignupContext, type WaitlistJoinResult } from './operations';
 import type { TypedDocumentNode } from '@graphql-typed-document-node/core';
 /** An access token + its rotating refresh token. */
 export interface FoirAuthTokens {
     token: string;
     refreshToken: string;
 }
-/** The customer identity carried by an auth result. */
-export interface FoirCustomer {
-    id: string;
-    email: string;
-}
-/** The resolved customer for a guarded surface. */
+/** The signed-in user an auth result and a session carry. */
 export interface FoirUser {
     id: string;
     email: string;
-    isAdmin: boolean;
 }
 /**
  * Injected session store. Methods may be sync or async so consumers can plug
@@ -44,39 +39,70 @@ export interface SessionAdapter {
     unset(key: string): void | Promise<void>;
 }
 /** Login with email + password. Requires the project to have passwords enabled. */
-export declare function customerLogin(env: FoirEnv, vars: {
+export declare function login(env: FoirEnv, vars: {
     email: string;
     password: string;
-}): Promise<CustomerAuthResult>;
-/** Register a new customer with email + password. */
-export declare function customerRegister(env: FoirEnv, vars: {
+}): Promise<AuthResult>;
+/** Register a new user with email + password. */
+export declare function register(env: FoirEnv, vars: {
     email: string;
     password: string;
-}): Promise<CustomerAuthResult>;
-/** Request a one-time password be emailed to the customer. */
-export declare function customerRequestOTP(env: FoirEnv, email: string): Promise<boolean>;
+}): Promise<AuthResult>;
+/** Request a one-time password be emailed to the user. */
+export declare function requestOTP(env: FoirEnv, email: string): Promise<boolean>;
 /** Complete an OTP login. */
-export declare function customerLoginOTP(env: FoirEnv, vars: {
+export declare function loginWithOTP(env: FoirEnv, vars: {
     email: string;
     otp: string;
-}): Promise<CustomerAuthResult>;
+}): Promise<AuthResult>;
 /** Rotate an access token using a refresh token. */
-export declare function customerRefreshToken(env: FoirEnv, refreshToken: string): Promise<CustomerAuthResult>;
+export declare function refreshTokens(env: FoirEnv, refreshToken: string): Promise<AuthResult>;
 /**
  * Initiate provider (OAuth/OIDC) login — returns a `redirectUrl` to send the
  * user to, or an inline `token` for non-redirect providers.
  */
-export declare function customerLoginWithProvider(env: FoirEnv, input: ProviderLoginInput): Promise<ProviderLoginResult>;
+export declare function loginWithProvider(env: FoirEnv, input: ProviderLoginInput): Promise<ProviderLoginResult>;
 /** Complete a provider login from the OAuth callback (`code`/`state`). */
-export declare function customerProviderCallback(env: FoirEnv, input: ProviderCallbackInput): Promise<CustomerAuthResult>;
+export declare function providerCallback(env: FoirEnv, input: ProviderCallbackInput): Promise<AuthResult>;
 /** Verify an OTP issued by an external provider. */
-export declare function customerProviderVerifyOTP(env: FoirEnv, input: ProviderOTPVerifyInput): Promise<CustomerAuthResult>;
+export declare function providerVerifyOTP(env: FoirEnv, input: ProviderOTPVerifyInput): Promise<AuthResult>;
+/**
+ * Why a provider sign-in did not finish, as the platform said it: a stable code
+ * your app shows its own words for (`signup_closed`, `provider_named_no_address`,
+ * `account_unavailable`, ...). When the code is `link_code_sent`, the sign-in
+ * named an address somebody already holds, through a provider that does not
+ * prove the address is theirs, and a code was sent to it: `pending` names the
+ * wait, and {@link confirmProviderLink} finishes the sign-in with that code.
+ * Null for any other failure.
+ */
+export declare function providerSignInRefusalOf(error: unknown): {
+    code: string;
+    pending?: string;
+} | null;
+/**
+ * Finish a provider sign-in that is waiting for the code sent to its address,
+ * connecting the provider to the account that holds the address. See
+ * {@link providerSignInRefusalOf}.
+ */
+export declare function confirmProviderLink(env: FoirEnv, input: {
+    pending: string;
+    code: string;
+}): Promise<AuthResult>;
+/**
+ * Send a new code for a provider sign-in that is waiting for one. The new code
+ * replaces the one before, and the answer names the new wait.
+ */
+export declare function resendProviderLinkCode(env: FoirEnv, input: {
+    pending: string;
+}): Promise<{
+    pending: string;
+}>;
 /** List the project's configured auth providers (for a login UI). */
 export declare function getAuthProviders(env: FoirEnv): Promise<AuthProviderPublic[]>;
 /**
  * Read the project's public auth configuration — which built-in methods are
  * enabled and which external providers to offer. This is what a login screen
- * renders itself from, before any customer token exists.
+ * renders itself from, before any user token exists.
  */
 export declare function getAuthConfig(env: FoirEnv): Promise<AuthConfig>;
 /**
@@ -85,55 +111,55 @@ export declare function getAuthConfig(env: FoirEnv): Promise<AuthConfig>;
  */
 export declare function getDefaultAuthProvider(env: FoirEnv): Promise<DefaultAuthProvider | null>;
 /**
- * Read the project's customer signup mode (public/restricted/waitlist/closed)
+ * Read the project's signup mode (public/restricted/waitlist/closed)
  * so a self-hosted frontend can render the right signup surface proactively.
  */
-export declare function customerSignupContext(env: FoirEnv): Promise<SignupContext>;
+export declare function signupContext(env: FoirEnv): Promise<SignupContext>;
 /** Join the project's signup waitlist. The project must be in waitlist mode. */
-export declare function customerJoinWaitlist(env: FoirEnv, email: string): Promise<WaitlistJoinResult>;
+export declare function joinWaitlist(env: FoirEnv, email: string): Promise<WaitlistJoinResult>;
 /**
  * Send a password-reset email. Resolves `true` whether or not the address has
  * an account: the server answers identically either way, on purpose, so this
  * endpoint cannot be used to test whether someone has signed up.
  */
-export declare function customerRequestPasswordReset(env: FoirEnv, email: string): Promise<boolean>;
+export declare function requestPasswordReset(env: FoirEnv, email: string): Promise<boolean>;
 /**
  * Redeem an emailed reset token and set a new password. Returns a fresh session
- * — resetting a password signs the customer in — so pair it with
+ * (resetting a password signs the user in), so pair it with
  * {@link saveSession}, or use {@link resetPasswordAndSignIn} which does both.
  */
-export declare function customerResetPassword(env: FoirEnv, vars: {
+export declare function resetPassword(env: FoirEnv, vars: {
     token: string;
     newPassword: string;
-}): Promise<CustomerAuthResult>;
+}): Promise<AuthResult>;
 /** Redeem an emailed verification token. */
-export declare function customerVerifyEmail(env: FoirEnv, token: string): Promise<boolean>;
+export declare function verifyEmail(env: FoirEnv, token: string): Promise<boolean>;
 /**
- * Change the calling customer's password. Requires the current password as well
+ * Change the calling user's password. Requires the current password as well
  * as the bearer, so a stolen token alone cannot take the account over.
  */
-export declare function customerUpdatePassword(env: FoirEnv, vars: {
+export declare function updatePassword(env: FoirEnv, vars: {
     currentPassword: string;
     newPassword: string;
 }, options?: AuthOpOptions): Promise<boolean>;
 /**
- * The calling customer, or `null` when the request carried no customer token.
+ * The calling user, or `null` when the request carried no user token.
  * An absent session is an answer rather than a failure, so this does not throw.
  */
 export declare function currentUser(env: FoirEnv, options?: AuthOpOptions): Promise<CurrentUser | null>;
 /**
- * The stored upstream provider token for the calling customer, refreshed
+ * The stored upstream provider token for the calling user, refreshed
  * transparently by the server when it has expired. `null` when there is no
- * customer token on the request or none stored for that provider.
+ * user token on the request or none stored for that provider.
  */
 export declare function myProviderToken(env: FoirEnv, providerKey: string, options?: AuthOpOptions): Promise<ProviderToken | null>;
 /**
  * End the session server-side, revoking stored provider tokens. This does NOT
  * clear local session state — {@link signOut} is the pairing that does both.
  */
-export declare function customerLogout(env: FoirEnv, options?: AuthOpOptions): Promise<boolean>;
+export declare function logout(env: FoirEnv, options?: AuthOpOptions): Promise<boolean>;
 /**
- * Delete the calling customer's account and their owned records and files.
+ * Delete the calling user's account and their owned records and files.
  * Irreversible. `password` is required for password accounts and omitted for
  * provider-only ones; the server enforces the actual re-auth gate and fails
  * closed, so omitting it is refused rather than allowed.
@@ -143,60 +169,140 @@ export declare function deleteMyAccount(env: FoirEnv, vars: {
     password?: string;
 }, options?: AuthOpOptions): Promise<DeleteAccountResult>;
 /**
- * The organizations this operator may stand in.
+ * Change the calling user's own name, picture or language. It asks no
+ * permission: these are theirs.
+ */
+export declare function updateMyProfile(env: FoirEnv, change: MyProfileChange, options?: AuthOpOptions): Promise<MyProfile>;
+/**
+ * The apps the calling user has agreed may act for them, and what each may
+ * carry: the list an account page shows with a way to take each one back.
+ */
+export declare function myAuthorizedApps(env: FoirEnv, options?: AuthOpOptions): Promise<AuthorizedApp[]>;
+/**
+ * Take back an app's authority to act for the calling user. Its tokens for
+ * them stop working at once, and it has to ask them again.
+ */
+export declare function revokeAuthorizedApp(env: FoirEnv, id: string, options?: AuthOpOptions): Promise<boolean>;
+/** Where the calling user is signed in, and the personal access tokens they hold. */
+export declare function mySessions(env: FoirEnv, options?: AuthOpOptions): Promise<MySession[]>;
+/** Sign the calling user out of one session, or revoke one of their tokens, by its id. */
+export declare function endMySession(env: FoirEnv, id: string, options?: AuthOpOptions): Promise<boolean>;
+/**
+ * Sign the calling user out of every session and every app, and answer how
+ * many sessions ended. Their personal access tokens stay. `keepThis` keeps the
+ * session making the request.
+ */
+export declare function signOutEverywhere(env: FoirEnv, vars?: {
+    keepThis?: boolean;
+}, options?: AuthOpOptions): Promise<number>;
+/**
+ * Make a personal access token for the calling user: a standing credential
+ * they present beside the app's key, as `Authorization: Bearer`. Its value is
+ * answered here once.
+ */
+export declare function createPersonalAccessToken(env: FoirEnv, vars: {
+    name: string;
+    expiresInDays: number;
+}, options?: AuthOpOptions): Promise<NewPersonalAccessToken>;
+/** The providers the calling user signs in with. */
+export declare function mySignInMethods(env: FoirEnv, options?: AuthOpOptions): Promise<MySignInMethod[]>;
+/**
+ * Start connecting one of the project's providers to the calling user's
+ * account, and answer the provider's address to send the browser to. It comes
+ * back to `returnTo` with `connected` or `connect_error` added.
+ */
+export declare function connectSignInMethod(env: FoirEnv, vars: {
+    provider: string;
+    returnTo: string;
+}, options?: AuthOpOptions): Promise<string>;
+/** Disconnect a provider from the calling user's account. */
+export declare function disconnectSignInMethod(env: FoirEnv, provider: string, options?: AuthOpOptions): Promise<boolean>;
+/** The second factors, passkeys and recovery codes the calling user holds. */
+export declare function myFactors(env: FoirEnv, options?: AuthOpOptions): Promise<MyFactor[]>;
+/**
+ * Begin proving a second factor with the calling user's password.
+ * {@link completeStepUp} finishes it; for a user who holds none, the answer's
+ * `elevatedHandle` is already the proof.
+ */
+export declare function beginStepUp(env: FoirEnv, password: string, options?: AuthOpOptions): Promise<StepUp>;
+/**
+ * Prove a second factor with exactly one of a passkey's or security key's
+ * assertion, an authenticator app's code or a recovery code, which is then
+ * spent. The session making the request counts as two factors from here, and
+ * the answer is an elevated handle for one change to the user's factors in
+ * the next ten minutes.
+ */
+export declare function completeStepUp(env: FoirEnv, vars: {
+    handle: string;
+    webauthnAssertionJson?: string;
+    totpCode?: string;
+    recoveryCode?: string;
+}, options?: AuthOpOptions): Promise<string>;
+/**
+ * Begin adding `totp` (an authenticator app), `webauthn` (a security key held
+ * as a second factor) or `passkey` (a passkey that signs the user in on its
+ * own), with the `elevatedHandle` {@link beginStepUp} or
+ * {@link completeStepUp} answered.
+ */
+export declare function beginFactorEnrollment(env: FoirEnv, vars: {
+    method: 'webauthn' | 'totp' | 'passkey';
+    elevatedHandle: string;
+}, options?: AuthOpOptions): Promise<FactorEnrollment>;
+/**
+ * Finish adding a second factor, with the `navigator.credentials.create`
+ * result or the authenticator app's code.
+ */
+export declare function completeFactorEnrollment(env: FoirEnv, vars: {
+    handle: string;
+    webauthnAttestationJson?: string;
+    totpCode?: string;
+    name?: string;
+}, options?: AuthOpOptions): Promise<boolean>;
+/** Remove one of the calling user's factors, with an elevated handle from {@link completeStepUp}. */
+export declare function removeFactor(env: FoirEnv, vars: {
+    elevatedHandle: string;
+    kind: string;
+    id: string;
+}, options?: AuthOpOptions): Promise<boolean>;
+/**
+ * Make the calling user new recovery codes, with an elevated handle from
+ * {@link completeStepUp}. They replace any held and are answered here once.
+ */
+export declare function makeRecoveryCodes(env: FoirEnv, elevatedHandle: string, options?: AuthOpOptions): Promise<string[]>;
+/**
+ * The organizations this user may stand in.
  *
- * Answered from the CALLING customer's own memberships: each organization they
- * hold one in and every organization beneath it, so an operator is shown
- * exactly the set they can stand in, and a customer with no memberships sees
- * an empty list rather than a refusal. Requires the customer bearer; it is not
- * the project's inventory and cannot be used as one.
+ * Answered from the calling user's own memberships: each organization they
+ * hold one in and every organization beneath it, so the list is exactly the
+ * set a request of theirs may name, and a user with no memberships sees an
+ * empty list rather than a refusal. Requires the user's bearer; it is not the
+ * project's inventory and cannot be used as one.
+ *
+ * A MEMBERSHIP REACHES DOWNWARD. Someone who is a member of an organization may
+ * stand in any organization beneath it without holding a row of their own
+ * there. The reverse never works: a membership at a branch stands in no
+ * ancestor and in no sibling branch, and a request naming either is refused as
+ * not-found, the same answer an organization that does not exist gets.
+ * {@link MyOrganization.role} names ONE of the roles that apply where the
+ * person stands (the membership held in the organization itself, when there is
+ * one); their authority there is the union of every membership that reaches
+ * it, together with their own roles in the project.
  */
 export declare function myOrganizations(env: FoirEnv, vars?: {
     first?: number;
     after?: string;
 }, options?: AuthOpOptions): Promise<MyOrganization[]>;
-/**
- * Stand in one of them, for this customer, until they choose otherwise.
- *
- * Set once — not per call. The selection is stored against the customer and
- * resolved into the claim on every subsequent request, so nothing downstream
- * takes an org argument. Pass an empty `orgId` to clear it and return to the
- * project-shared view.
- *
- * The server authorises the choice against a live membership and refuses
- * otherwise, so a caller cannot select their way into an organization they do
- * not run.
- *
- * A MEMBERSHIP REACHES DOWNWARD, which is what "a live membership" means now
- * that organizations nest. Someone who is a member of an organization may stand in any
- * organization BENEATH it without holding a row of their own there, and
- * {@link myOrganizations} offers exactly that set — so any id it returned can
- * be passed here. The reverse never works: a membership at a branch stands in
- * no ancestor and in no sibling branch, and both are refused as not-found,
- * which is the same answer an organization that does not exist gets.
- *
- * WHAT STANDING THERE MEANS is every membership that reaches the organization
- * selected. Reach a client through a membership above it and the role shown is
- * that membership's; authority is the union of every membership that reaches
- * it, together with the customer's own roles in the project.
- * {@link MyOrganization.role} names ONE of those roles (the membership held in
- * the organization itself, when there is one), so it is part of what the next
- * request resolves and not the whole of it.
- */
-export declare function selectOrganization(env: FoirEnv, vars: {
-    orgId: string;
-}, options?: AuthOpOptions): Promise<SelectedOrganization>;
 /**
  * Found an organization, as its first member.
  *
  * The caller decides the NAME and, optionally, where it hangs — and nothing
- * else. The founder is the customer behind the bearer, the id is minted
+ * else. The founder is the user behind the bearer, the id is minted
  * server-side the way a project's and a tenant's are, and the role they hold in
  * the new organization is the one the PROJECT named in its settings
- * (`operatorSignupRole`). The server creates the organization and that one
+ * (`organizationSignupRole`). The server creates the organization and that one
  * membership together.
  *
- * `parentId` FOUNDS A CHILD, which is what lets your own customer create its own
+ * `parentId` FOUNDS A CHILD, which is what lets the people you serve create their own
  * sub-tenants with no administrator in the loop — a reseller adding a client, a
  * franchise adding a branch. It is resolved against the caller's own
  * MEMBERSHIPS, not merely against the project: on this lane "an organization
@@ -204,59 +310,59 @@ export declare function selectOrganization(env: FoirEnv, vars: {
  * not-found. Omit it to found a root, which is what every registration did
  * before organizations nested.
  *
- * Exists on the wire only while the project's `operatorSignupEnabled` setting
+ * Exists on the wire only while the project's `organizationSignupEnabled` setting
  * is on; a project that never opted in has no such field, and this refuses
  * naming it. Returns the same entry `myOrganizations` would then list, role
- * included, so the application can go straight to {@link selectOrganization}.
+ * included, so the application can name it on its next request.
  */
 export declare function registerOrganization(env: FoirEnv, vars: {
     name: string;
     parentId?: string;
 }, options?: AuthOpOptions): Promise<MyOrganization>;
 /**
- * Persist an auth result to the session; returns the customer identity.
+ * Persist an auth result to the session; returns the signed-in user.
  *
- * A result that names no customer keeps the identity already stored. A refresh
+ * A result that names no user keeps the identity already stored. A refresh
  * rotates the tokens of a session that already knows who it belongs to, and a
- * platform that answers a refresh without the customer must not blank that:
+ * platform that answers a refresh without the user must not blank that:
  * {@link requireAuth} reads the stored identity, so a valid token beside an
  * empty identity reads as signed out.
  */
-export declare function saveSession(adapter: SessionAdapter, result: CustomerAuthResult): Promise<FoirCustomer>;
+export declare function saveSession(adapter: SessionAdapter, result: AuthResult): Promise<FoirUser>;
 /** Clear all Foir auth keys from the session. */
 export declare function clearSession(adapter: SessionAdapter): Promise<void>;
 /** Read the stored access token (null when signed out). */
 export declare function getSessionToken(adapter: SessionAdapter): Promise<string | null>;
-/** Read the stored customer identity (null when signed out). */
-export declare function getSessionCustomer(adapter: SessionAdapter): Promise<FoirCustomer | null>;
+/** Read the stored user (null when signed out). */
+export declare function getSessionUser(adapter: SessionAdapter): Promise<FoirUser | null>;
 /** Login with email + password and persist the session. */
-export declare function loginWithPassword(adapter: SessionAdapter, env: FoirEnv, vars: {
+export declare function signInWithPassword(adapter: SessionAdapter, env: FoirEnv, vars: {
     email: string;
     password: string;
-}): Promise<FoirCustomer>;
+}): Promise<FoirUser>;
 /** Register with email + password and persist the session. */
-export declare function registerWithPassword(adapter: SessionAdapter, env: FoirEnv, vars: {
+export declare function signUpWithPassword(adapter: SessionAdapter, env: FoirEnv, vars: {
     email: string;
     password: string;
-}): Promise<FoirCustomer>;
+}): Promise<FoirUser>;
 /** Complete an OTP login and persist the session. */
-export declare function loginWithOTP(adapter: SessionAdapter, env: FoirEnv, vars: {
+export declare function signInWithOTP(adapter: SessionAdapter, env: FoirEnv, vars: {
     email: string;
     otp: string;
-}): Promise<FoirCustomer>;
+}): Promise<FoirUser>;
 /**
  * Complete a forgot-password flow: redeem the emailed token, set the new
  * password, and persist the session the server mints. The peer of
- * {@link loginWithPassword} for the branch where the customer cannot log in.
+ * {@link signInWithPassword} for the branch where the user cannot log in.
  */
 export declare function resetPasswordAndSignIn(adapter: SessionAdapter, env: FoirEnv, vars: {
     token: string;
     newPassword: string;
-}): Promise<FoirCustomer>;
+}): Promise<FoirUser>;
 /**
  * End the session on both sides: revoke it server-side, then clear local state.
  *
- * The local clear happens even when the server call fails. A customer who
+ * The local clear happens even when the server call fails. Someone who
  * pressed sign-out and got a network error must not be left holding a session
  * on the device in front of them — the token expires on its own, and the
  * failure mode of clearing anyway (one orphaned provider token) is strictly
@@ -295,16 +401,18 @@ export declare function authedRequest<TData, TVariables>(adapter: SessionAdapter
  * management, which is the half a generated namespace does not give you.
  */
 export declare function authedOp<T>(adapter: SessionAdapter, env: FoirEnv, op: AuthOpName, args?: Record<string, unknown>): Promise<T>;
-export interface RequireAuthOptions {
+export interface RequireAuthOptions<TUser = FoirUser> {
     /**
-     * Resolve the full {@link FoirUser} (including the project-specific
-     * `isAdmin`) from the session identity. Typically runs the project's
-     * `myProfile` query via {@link authedRequest}. Defaults to `isAdmin: false`.
+     * Resolve what the guarded surface needs about the user from the session:
+     * typically the project's own profile record, read through
+     * {@link authedRequest}. Without it the guard answers the {@link FoirUser}
+     * the session holds. What the user may do is a role or a scope: guard on
+     * those with {@link requireRole} and {@link requireScope}.
      */
     resolveUser?: (ctx: {
         token: string;
-        customer: FoirCustomer;
-    }) => FoirUser | Promise<FoirUser>;
+        user: FoirUser;
+    }) => TUser | Promise<TUser>;
     /**
      * Called when there's no valid session — throw your framework's redirect
      * (e.g. `throw redirect(loginUrl)`). Must not return.
@@ -319,14 +427,8 @@ export interface RequireAuthOptions {
     env?: FoirEnv;
 }
 /**
- * Require a signed-in customer. Resolves the {@link FoirUser} via
- * `resolveUser` (or a minimal identity), or invokes `onUnauthenticated` when
- * there's no session.
+ * Require a signed-in user. Answers what `resolveUser` resolves (or the
+ * session's {@link FoirUser}), or invokes `onUnauthenticated` when there's no
+ * session.
  */
-export declare function requireAuth(adapter: SessionAdapter, options: RequireAuthOptions): Promise<FoirUser>;
-export interface RequireAdminOptions extends RequireAuthOptions {
-    /** Called when the user is authenticated but not an admin. Must not return. */
-    onForbidden: () => never | Promise<never>;
-}
-/** Require a signed-in customer who is also an admin. */
-export declare function requireAdmin(adapter: SessionAdapter, options: RequireAdminOptions): Promise<FoirUser>;
+export declare function requireAuth<TUser = FoirUser>(adapter: SessionAdapter, options: RequireAuthOptions<TUser>): Promise<TUser>;

package/dist/auth/hosted.d.ts

@@ -1,11 +1,11 @@
 /**
  * Hosted-login bridge — for storefronts that delegate sign-in to a Foir
- * white-label front door (the `customerLoginWithFoir` flow) instead of
+ * white-label front door (the `loginWithFoir` flow) instead of
  * rendering their own login UI.
  *
  * The front door sets a first-party session cookie on the registrable domain;
  * because that domain is shared, the cookie reaches the storefront, which
- * exchanges it server-side for a short-lived customer bearer + identity. The
+ * exchanges it server-side for a short-lived user bearer + identity. The
  * cookie is the durable credential (re-exchanged on bearer expiry) — there's
  * no separate refresh token in this flow.
  *
@@ -15,7 +15,7 @@
 export interface HostedLoginConfig {
     /** White-label front-door origin, e.g. `https://login.example.com`. */
     loginOrigin: string;
-    /** Session cookie name set on the registrable domain. Default `foir_customer_session`. */
+    /** Session cookie name set on the registrable domain. Default `foir_session`. */
     cookieName?: string;
     /** Session-exchange path on the front door. Default `/session/token`. */
     sessionPath?: string;
@@ -29,13 +29,13 @@ export interface HostedLoginConfig {
 export declare function hostedLoginUrl(config: HostedLoginConfig, returnTo?: string): string;
 /**
  * Build the redirect URL that ENDS the hosted session — the mirror of
- * `hostedLoginUrl`, and the only thing that actually signs a customer out on
+ * `hostedLoginUrl`, and the only thing that actually signs a user out on
  * this flow.
  *
  * The cookie is the durable credential. Disposing of a bearer, clearing a
- * local session, or calling the `customerLogout` mutation (which clears
+ * local session, or calling the `logout` mutation (which clears
  * upstream provider tokens and nothing else) all leave it in place, and the
- * next request re-establishes the customer from it. This URL points at the
+ * next request re-establishes the user from it. This URL points at the
  * front door's end-session endpoint, which revokes the session row and clears
  * the cookie before returning the browser to `returnTo`.
  *
@@ -50,7 +50,7 @@ export declare function hostedLogoutUrl(config: HostedLoginConfig, clientId: str
 /** The identity + bearer returned by a successful hosted-session exchange. */
 export interface HostedSession {
     token: string;
-    customerId: string;
+    userId: string;
     email: string;
     /**
      * Seconds until `token` lapses, from the endpoint's `expires_in`.
@@ -61,7 +61,7 @@ export interface HostedSession {
      * lifetime (coupling a storefront to a server constant it cannot see) or to
      * decode `exp` off the JWT. Both re-derive a number the response already
      * carried, and a consumer that does neither treats a 15-minute bearer as good
-     * forever — which reads as a customer being signed out mid-session.
+     * forever — which reads as a user being signed out mid-session.
      *
      * Store the death date, not this number: it is seconds from when the exchange
      * ANSWERED, and a value held across requests is already stale.
@@ -76,9 +76,9 @@ export interface HostedSession {
  * reason says what happened.
  *
  * Collapsing all of this to `null` is what made a transient blip on
- * `/session/token` indistinguishable from a genuinely signed-out customer. The
+ * `/session/token` indistinguishable from a genuinely signed-out user. The
  * only safe-looking action on a bare `null` is to clear the session and send
- * the customer to the front door, so one 502 signed out a customer whose 30-day
+ * the user to the front door, so one 502 signed out a user whose 30-day
  * cookie was perfectly valid — and the route's rate limiter is deliberately
  * fail-open for exactly the opposite reason ("a Redis outage should degrade an
  * authenticated app, not log it out").
@@ -90,7 +90,7 @@ export type HostedSessionResult =
     session: HostedSession;
 }
 /**
- * The customer is signed out. Act on it: clear any local session and send
+ * The user is signed out. Act on it: clear any local session and send
  * them to `hostedLoginUrl`.
  *
  * `no-cookie` — nothing to exchange. `rejected` — the front door refused the
@@ -102,12 +102,12 @@ export type HostedSessionResult =
 }
 /**
  * The exchange could not be completed, and it says NOTHING about whether the
- * customer is signed in. KEEP the existing session, serve the request, try
+ * user is signed in. KEEP the existing session, serve the request, try
  * again on the next one.
  *
  * `forbidden` is the odd one: a 403 means the CSRF header did not arrive
  * (a proxy stripping it, most likely), which is a misconfiguration rather
- * than a blip. Retrying will not fix it — but signing the customer out would
+ * than a blip. Retrying will not fix it — but signing the user out would
  * be wrong, so the safe action is the same and it is grouped by that.
  */
  | {
@@ -119,7 +119,7 @@ export type HostedSessionResult =
     cause?: unknown;
 };
 /**
- * Exchange the hosted-login cookie on an incoming request for a customer
+ * Exchange the hosted-login cookie on an incoming request for a user
  * bearer + identity (server-to-server: forwards the cookie to the front door's
  * session endpoint with the CSRF header).
  *

package/dist/auth/index.d.ts

@@ -1,8 +1,8 @@
 /**
- * `@foir/sdk/auth` — framework-agnostic Foir customer auth.
+ * `@foir/sdk/auth`: framework-agnostic sign-in for your app's users.
  *
- * The whole customer auth surface — login, register, OTP, external providers,
- * refresh, password management, email verification and account deletion — over
+ * The whole sign-in surface (login, register, OTP, external providers,
+ * refresh, password management, email verification and account deletion) over
  * the server's generated `auth` namespace, plus token lifecycle with an
  * injected `SessionAdapter`, guards, and the optional hosted-login bridge.
  *
@@ -10,9 +10,9 @@
  * the caller's own manifest advertises, through the same op transport
  * `@foir/sdk/data` uses, so `graphql` is not on this module's path at all.
  */
-export { customerLogin, customerRegister, customerRequestOTP, customerLoginOTP, customerRefreshToken, customerLoginWithProvider, customerProviderCallback, customerProviderVerifyOTP, getAuthProviders, getAuthConfig, getDefaultAuthProvider, customerSignupContext, customerJoinWaitlist, customerRequestPasswordReset, customerResetPassword, customerUpdatePassword, customerVerifyEmail, currentUser, myProviderToken, customerLogout, deleteMyAccount, myOrganizations, selectOrganization, registerOrganization, saveSession, clearSession, getSessionToken, getSessionCustomer, loginWithPassword, registerWithPassword, loginWithOTP, resetPasswordAndSignIn, refreshSession, refreshSessionOnce, signOut, authedRequest, authedOp, requireAuth, requireAdmin, } from './auth';
-export type { FoirAuthTokens, FoirCustomer, FoirUser, SessionAdapter, RequireAuthOptions, RequireAdminOptions, } from './auth';
-export { customerAccess, getSessionAccess, hasRole, hasScope, requireRole, requireScope, FoirAccessDeniedError, } from './access';
+export { login, register, requestOTP, loginWithOTP, refreshTokens, loginWithProvider, providerCallback, providerVerifyOTP, providerSignInRefusalOf, confirmProviderLink, resendProviderLinkCode, getAuthProviders, getAuthConfig, getDefaultAuthProvider, signupContext, joinWaitlist, requestPasswordReset, resetPassword, updatePassword, verifyEmail, currentUser, myProviderToken, logout, deleteMyAccount, updateMyProfile, myAuthorizedApps, revokeAuthorizedApp, mySessions, endMySession, signOutEverywhere, createPersonalAccessToken, mySignInMethods, connectSignInMethod, disconnectSignInMethod, myFactors, beginStepUp, completeStepUp, beginFactorEnrollment, completeFactorEnrollment, removeFactor, makeRecoveryCodes, myOrganizations, registerOrganization, saveSession, clearSession, getSessionToken, getSessionUser, signInWithPassword, signUpWithPassword, signInWithOTP, resetPasswordAndSignIn, refreshSession, refreshSessionOnce, signOut, authedRequest, authedOp, requireAuth, } from './auth';
+export type { FoirAuthTokens, FoirUser, SessionAdapter, RequireAuthOptions, } from './auth';
+export { userAccess, getSessionAccess, hasRole, hasScope, requireRole, requireScope, FoirAccessDeniedError, } from './access';
 export type { FoirAccess, FoirAccessDenial } from './access';
 export { FoirAuthDowngradedError, FoirSessionExpiredError } from '../graphql/foir-request';
 export { AUTH_OPS } from './ops';
@@ -21,4 +21,4 @@ export { hostedLoginUrl, hostedLogoutUrl, fetchHostedSession } from './hosted';
 export type { HostedLoginConfig, HostedSession, HostedSessionResult } from './hosted';
 export { createFoirSessionClient } from './session-client';
 export type { FoirSessionClient, FoirSessionConfig, FoirSessionUser, } from './session-client';
-export type { CustomerAuthResult, ProviderLoginResult, AuthProviderPublic, ProviderLoginInput, ProviderCallbackInput, ProviderOTPVerifyInput, SignupContext, SignupMode, WaitlistJoinResult, AuthConfig, AuthConfigProvider, DefaultAuthProvider, CurrentUser, ProviderToken, DeleteAccountResult, MyOrganization, SelectedOrganization, } from './operations';
+export type { AuthResult, ProviderLoginResult, AuthProviderPublic, ProviderLoginInput, ProviderCallbackInput, ProviderOTPVerifyInput, SignupContext, SignupMode, WaitlistJoinResult, AuthConfig, AuthConfigProvider, DefaultAuthProvider, CurrentUser, ProviderToken, DeleteAccountResult, MyOrganization, MyProfile, MyProfileChange, AuthorizedApp, MySession, NewPersonalAccessToken, MySignInMethod, MyFactor, StepUp, FactorEnrollment, } from './operations';