@foir/sdk 0.21.0 → 0.23.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,80 @@ 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;
+/**
+ * Why a sign-in your app's own form sent was refused, as the platform said it:
+ * a stable code your app shows its own words for. `password_sign_in_off` from
+ * {@link login} or {@link register} where the project, or the app the sign-in
+ * came through, takes no password; `code_sign_in_off` from {@link requestOTP}
+ * or {@link loginWithOTP} where it takes no code. Null for any other failure.
+ */
+export declare function signInRefusalOf(error: unknown): {
+    code: 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 +121,69 @@ 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.
+ *
+ * `clientId` names your app. Where the email's link goes to Foir's hosted
+ * reset page (the project has no App base URL), the page then sends the user
+ * to your app's initiate login URL to sign in.
  */
-export declare function customerRequestPasswordReset(env: FoirEnv, email: string): Promise<boolean>;
+export declare function requestPasswordReset(env: FoirEnv, email: string, options?: {
+    clientId?: 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
- * transparently by the server when it has expired. `null` when there is no
- * customer token on the request or none stored for that provider.
+ * The stored upstream provider token for the calling user, renewed by the
+ * server when it is due: near its stated expiry, or with no expiry stated.
+ * `null` when there is no user token on the request; `linked: false` when the
+ * user has none stored for that provider.
+ *
+ * Pass `forceRefresh` after the provider refused the token it was last given:
+ * the server renews it then, at most once a minute for one user and provider.
+ * `refresh` says what the read did, and `reauthenticate` says when only the
+ * user signing in with the provider again mends the connection.
  */
-export declare function myProviderToken(env: FoirEnv, providerKey: string, options?: AuthOpOptions): Promise<ProviderToken | null>;
+export declare function myProviderToken(env: FoirEnv, providerKey: string, options?: AuthOpOptions & {
+    forceRefresh?: boolean;
+}): 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 +193,141 @@ 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. A user whose
+ * role holds `organizations:read` in the project is listed every organization
+ * of it instead, suspended ones included.
+ *
+ * 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
+ * The caller decides the NAME and, optionally, where it hangs and where it
+ * lives — and nothing 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 +335,66 @@ 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
+ * `appBaseUrl` is where the organization's app lives, so an app that finds its
+ * organization from the page address (`orgUrl`) finds this one at once. It is
+ * held to the rule every organization address is: under the project's own app
+ * address or a domain the project verified, and not one another organization
+ * of the project holds.
+ *
+ * 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;
+    appBaseUrl?: 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 +433,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 +459,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/grant-table.generated.d.ts

@@ -1,12 +1,13 @@
 export type GrantReach = 'own' | 'named' | 'all';
+export type GrantTarget = 'none' | 'model' | 'operation';
 /**
- * One permission: its name, whether a grant of it may name a target, the
- * reaches it may be granted at (none: only its bare form exists), and the
- * grants a holder of it also holds.
+ * One permission: its name, what a grant of it may name, the reaches it may be
+ * granted at (none: only its bare form exists), and the grants a holder of it
+ * also holds.
  */
 export type GrantTableRow = readonly [
     name: string,
-    takesTarget: boolean,
+    target: GrantTarget,
     reaches: readonly GrantReach[],
     implies: readonly string[]
 ];