@authowl/core 0.22.0 → 0.23.0

package/dist/{client-BHufZSky.d.ts → config-CyUwyJ9B.d.cts}

@@ -1,282 +1,265 @@
-import { R as ResolvedAuthConfig, H as HasParams, O as OrganizationMembership } from './organization-membership-BIify9hZ.js';
-
-/**
- * The organization invitation an emailed link is asking this browser to accept.
- *
- * The link lands on the TENANT'S OWN page carrying `?authowl_invitation=<id>`,
- * and the only route that can redeem it needs a session the visitor usually does
- * not have yet. So the id has to survive an entire sign-up or sign-in - which
- * means surviving that flow's redirects: the OAuth round trip, the email
- * verification round trip (which can land on a different page entirely), the MFA
- * hold, and whatever navigation the operator's own `redirectTo` performs. A query
- * parameter survives none of those, so it is read once, moved into storage, and
- * taken out of the URL.
- *
- * Best-effort storage, deliberately: a browser that refuses `localStorage`
- * degrades to "this invitation is claimable until you navigate", which is worse
- * than the ideal and much better than a sign-in that throws.
- */
-declare const INVITATION_QUERY_PARAM = "authowl_invitation";
-/**
- * The only hint value that exists. There is deliberately no `existing_user`:
- * absence has to stay ambiguous across an existing account, an older AuthOwl,
- * and an account created between the invite and the click - so it can never be
- * read as proof that an address IS registered.
- */
-type InvitationRecipientHint = 'new_user';
-type InvitationClaim = {
-    id: string;
-    /** Epoch milliseconds, for age display and for expiring a forgotten claim. */
-    capturedAt: number;
+type DecodedPublishableKey = {
+    prefix: 'pk_live' | 'pk_test';
+    env: 'live' | 'test';
+    projectId: string;
 };
-/** Claims older than this are dropped unread: a month-old link is not a pending intent. */
-declare const INVITATION_CLAIM_MAX_AGE_MS: number;
-/**
- * Read `?authowl_invitation` once, stash it, and strip it from the URL.
- *
- * Namespaced and only ours - a bare `invitation` belongs to the tenant's app as
- * much as to us, and rewriting their parameters is not ours to do. Returns the
- * captured claim, or the one already stashed when there is no parameter, so a
- * caller can render from a single call.
- */
-declare function captureInvitationClaim(now?: number): InvitationClaim | null;
-/** The stashed claim, or null when there is none, it is unreadable, or it is stale. */
-declare function readInvitationClaim(now?: number): InvitationClaim | null;
-declare function clearInvitationClaim(): void;
+declare function decodePublishableKey(key: string): DecodedPublishableKey;
 
-type EnvironmentType = 'development' | 'production';
-/**
- * The public, publishable-key-safe project config the SDK renders its sign-in
- * UI from (server contract CONTRACTS §2, `GET /api/projects/:id/public-config`).
- * Nothing here is secret. Method slugs are canonical snake_case.
- */
+/** How a session BEGINS, as the minting door knows it. */
+type SessionStart = {
+    /**
+     * Whether the session is meant to outlive the tab.
+     *
+     * `dont_remember` is a SECOND cookie, and on the browsers this transport
+     * exists for it is dropped exactly like the session cookie is - so the engine
+     * never sees it and treats every bearer session as persistent. The token is
+     * the only copy of that session the SDK controls, so "don't remember me" has
+     * to be honoured by WHERE it is kept: `sessionStorage`, which dies with the
+     * tab, rather than `localStorage`, which does not.
+     *
+     * NOTE the behaviour change that buys: `sessionStorage` is per TAB, where
+     * `dont_remember` was per browser session. A "don't remember me" bearer
+     * session is therefore not shared with other tabs. That is deliberate and it
+     * is the safe direction (a session that ends too soon rather than one that
+     * outlives the machine's owner), but it is a real difference from the cookie
+     * transport and callers should not discover it by accident.
+     */
+    remember: boolean;
+};
+/** Secret-free events for framework adapters that project the current session. */
+type SessionLifecycleEvent = Readonly<{
+    type: 'beginSession';
+    remember: boolean;
+}> | Readonly<{
+    type: 'endSession';
+}>;
 /**
- * A project's configured bot challenge.
+ * One session read, from the moment it is dispatched to the moment it answers.
  *
- * `provider` is deliberately a plain string rather than a union of the ones this
- * SDK can render. A project may be switched to a provider that predates the
- * copy of the SDK an application is running, and the difference between
- * "no challenge configured" and "a challenge this build cannot render" is the
- * difference between signing in and a silent 403 the user cannot act on. Keeping
- * the slug lets the renderer say which provider it does not know.
+ * Cut by the store, so the rule about which answers may be acted on lives with
+ * the state it protects rather than being restated by every caller. The token
+ * the read is about is captured INSIDE it: `hasToken` explains why nothing hands
+ * the credential out, and a receipt that leaked it would be the same hole with a
+ * shorter lifetime.
  */
-interface CaptchaConfig {
-    provider: string;
-    siteKey: string;
-}
-type PublicConfig = {
-    /** Stable workspace product container shared by its environments. */
-    applicationId: string;
-    /** Stable tenant id for the exact environment selected by the publishable key. */
-    environmentId: string;
-    /** Environment class that determines key prefixes and billing treatment. */
-    environmentType: EnvironmentType;
+type SessionRead = {
     /**
-     * Authentication endpoint used by this SDK instance. Hosted portals and
-     * custom domains keep this same-origin even when the stable JWT issuer uses
-     * the platform's canonical origin.
+     * Whether the read this receipt was cut for actually presented a token.
+     *
+     * The cookie measurement turns on it: a read that carried NO token and still
+     * found a session IS the proof that our cross-site cookie survives here.
      */
-    authBaseUrl: string;
+    readonly carriedToken: boolean;
     /**
-     * Public acquisition mode. Optional only for rolling compatibility with
-     * servers released before waitlist support.
+     * The read came back with no session. End the session it was reading - unless
+     * the token it presented is no longer the session in play.
+     *
+     * This is the path-independent catch for every ending that is not sign-out:
+     * expiry, a revoke from another device, `account.revokeSession` called with
+     * your own id, `account.delete`, an admin ban. None of those are visible in
+     * the response to the call that caused them, and a token we PRESENTED and got
+     * nothing back for is dead by definition.
      */
-    signUp?: {
-        mode: 'open' | 'restricted' | 'allowlist' | 'waitlist';
-    };
+    endIfDead(): void;
     /**
-     * Identity and credential lifecycle policy. Optional only for rolling
-     * compatibility with AuthOwl servers released before plan 35.
+     * Record what this read proved about the browser's cookies. `true` means the
+     * cookie came back and no token is needed here.
+     *
+     * On the receipt rather than on the store, because a detached read answers
+     * "there is no cookie session" for two completely different reasons, and only
+     * one of them is about the browser. A probe dispatched for one session and
+     * answered after that session ENDED - a sign-out, or a sign-out and a fresh
+     * sign-in, both of which fit inside one probe's round trip - reports the
+     * signed-out gap as a broken cookie. Acting on it would record `bearer` on a
+     * browser whose cookies are fine and then persist the NEXT session's token to
+     * disk under it, which is the exact defect this gate exists to remove, and it
+     * would stick until the sign-in after next.
+     *
+     * Two facts here, with different authorities, and reading them as one is what
+     * this comment used to license. RECORDING the verdict needs no token-value
+     * comparison of the kind `endIfDead` does: it is a statement about the
+     * BROWSER, every tab on this origin is the same browser, and a verdict
+     * wrongly skipped only costs another measurement. The WRITE it unlocks is the
+     * opposite - the token this receipt closed over is at least a probe round trip
+     * old, and across tabs arbitrarily old, so flushing it unguarded puts a
+     * superseded credential into the slot every tab shares. See `flushHeldToken`,
+     * which is where that write goes and why.
      */
-    authentication?: {
-        email: {
-            signUp: boolean;
-            signIn: Array<'password' | 'magic_link' | 'email_otp'>;
-        };
-        phone: {
-            signUp: boolean;
-            signIn: boolean;
-        };
-        password: {
-            signUp: boolean;
-            add: boolean;
-            /** Server-owned password length policy. Optional for rolling compatibility. */
-            minLength?: number;
-            maxLength?: number;
-        };
-        passkey: {
-            signIn: boolean;
-            add: boolean;
-            /**
-             * The domain this environment binds passkeys to. Absent or null means the
-             * server derives it from the auth host, which is what every server before
-             * this field did - so treating both the same keeps a new SDK correct
-             * against an older server.
-             */
-            relyingPartyId?: string | null;
-        };
-        username: {
-            collectOnSignUp: boolean;
-            signIn: boolean;
-        };
-    };
-    /** Email ownership ceremony selected by the project. */
-    emailVerification?: {
-        required: boolean;
-        method: 'link' | 'code';
-    };
-    /** End-user profile fields and self-service permissions. */
-    userModel?: {
-        requireEmail: boolean;
-        firstLastName: boolean;
-        emailChange: boolean;
-        accountDeletion: boolean;
-    };
+    recordCookieVerdict(cookiesWork: boolean): void;
+};
+type SessionTokenStore = {
+    /** Observe lifecycle changes without receiving the token or proof key. */
+    subscribeLifecycle(listener: (event: SessionLifecycleEvent) => void): () => void;
     /**
-     * MFA presentation contract. Backup codes follow TOTP and are not an
-     * independently configurable authentication method.
+     * Whether a token is held. Deliberately not a getter for the token itself:
+     * `declareOn` is the only thing that puts it on the wire, so nothing else
+     * needs the credential in hand.
      */
-    mfa?: {
-        totp: boolean;
-        required: boolean;
-        backupCodes: boolean;
-    };
-    branding: {
-        appName?: string;
-        logoUrl?: string;
-        /** Whether the application name is visible beside the logo. */
-        showAppName?: boolean;
-        /** Alignment of the brand identity within managed component headers. */
-        alignment?: 'left' | 'center' | 'right';
-        primaryColor?: string;
-        theme?: 'light' | 'dark' | 'system';
-    };
-    /** Canonical method slugs, e.g. "password", "magic_link", "passkey". */
-    enabledMethods: string[];
-    /** Configured social provider ids, e.g. "google". */
-    socialProviders: string[];
+    hasToken(): boolean;
+    /** Thumbprint paired with the current token, or null for a legacy unbound session. */
+    bindingThumbprint(): string | null;
     /**
-     * Public OAuth client ids keyed by provider. Optional for rolling compatibility
-     * with servers released before Google One Tap support.
+     * Put this request on the transport - EVERY header, or none of them.
+     *
+     * The declaration, the bearer when one is held, and the challenge when one is
+     * held. Returns whether it declared, which is also the only condition under
+     * which the response can carry either cargo back.
+     *
+     * The challenge rides here rather than at whichever call site knows it is
+     * doing 2FA, and that is the point of the shape: `dont_remember` outlives the
+     * challenge it arrived with - `get-session` reads it for the life of the
+     * session to decide expiry refresh - so a store presented only when answering
+     * a code leaves a "don't remember me" session quietly resuming refresh. A
+     * request that is on this transport at all is on it for both cargoes.
      */
-    socialProviderClientIds?: Record<string, string>;
+    declareOn(headers: Headers): boolean;
     /**
-     * When true, an email/password sign-up does not create a session - the user
-     * must confirm their address first. <SignUp/> shows a "check your email" state
-     * instead of redirecting. Always false unless password sign-up is enabled.
+     * Whether this transport is still in play at all - for EITHER cargo, since one
+     * declaration governs both.
+     *
+     * False only once cookies are PROVEN to work here, after which `declareOn`
+     * changes nothing and no response can carry a token or a challenge back - so a
+     * caller may skip the decoration entirely rather than copy headers it will not
+     * touch. A browser that keeps our cookies keeps the ticket in its jar, where it
+     * is HttpOnly and strictly safer than anything a header can carry.
      */
-    requireEmailVerification: boolean;
+    wantsToken(): boolean;
+    /** Whether this browser's cookie behaviour is still unmeasured. */
+    needsProbe(): boolean;
     /**
-     * Legal consent gate. When `required`, <SignUp/> shows an acceptance checkbox
-     * linking `termsUrl`/`privacyUrl` and blocks sign-up until it's checked, echoing
-     * `version` back so the server records and enforces it. `required` is true only
-     * when the project both requires consent and has a document URL to link.
+     * Capture a token the server handed back, and put it where it belongs.
+     *
+     * "Where it belongs" is MEMORY until the cookie has demonstrably failed. The
+     * verdict is not knowable at the moment of capture and the token is not needed
+     * on most browsers, so the safe order is to hold it, ask, and write only if
+     * the answer says this browser has no other way to keep a session. Capturing
+     * one is also what ASKS the question - see `measureWith` - because a gate on a
+     * measurement nobody runs is just a session that dies at the next reload.
      */
-    legal: {
-        termsUrl?: string;
-        privacyUrl?: string;
-        version: number;
-        required: boolean;
-    };
-    /** Published, bilingual privacy notices and optional consent purposes. */
-    privacy?: {
-        notices: Array<{
-            noticeId: string;
-            noticeVersionId: string;
-            code: string;
-            version: number;
-            title: {
-                en: string;
-                ar: string;
-            };
-            body: {
-                en: string;
-                ar: string;
-            };
-            digest: {
-                en: string;
-                ar: string;
-            };
-            activityCodes: string[];
-            purposeCodes: string[];
-            effectiveFrom: string;
-        }>;
-        consentPurposes: Array<{
-            purposeId: string;
-            purposeVersionId: string;
-            code: string;
-            version: number;
-            title: {
-                en: string;
-                ar: string;
-            };
-            description: {
-                en: string;
-                ar: string;
-            };
-            digest: {
-                en: string;
-                ar: string;
-            };
-            activityCodes: string[];
-            dataCategories: string[];
-        }>;
-    };
+    observe(headers: Headers): void;
     /**
-     * Whether the project lets signed-in users enrol a second factor (TOTP). A
-     * capability flag, not a sign-in method (so it's absent from `enabledMethods`):
-     * gate an "enable two-factor" affordance / <MFAEnrollment/> on it. The sign-in
-     * 2FA challenge is handled by <SignIn/> regardless of this flag.
+     * The server rejected the challenge this store presented: the ticket is spent,
+     * expired, or was never there, and the user has to start at the first factor
+     * again.
+     *
+     * Separate from `endSession` because no session ended - the challenge one was
+     * pending on did. Keeping the store instead would present a dead ticket on
+     * every later request, and keep a `dont_remember` that no longer describes
+     * anything, for as long as the tab lives.
      */
-    twoFactor: boolean;
-    /** Whether enrolled MFA is mandatory rather than optional for this project. */
-    mfaRequired: boolean;
-    /** Whether signed-in users may delete their own account. */
-    accountDeletion: boolean;
-    /** Whether organization routes and components are available for this project. */
-    organizations: boolean;
+    dropChallenge(): void;
     /**
-     * Whether inbound enterprise SSO is enabled for this project. SSO IS a sign-in
-     * method, so when true the server also pushes `'sso'` into `enabledMethods`;
-     * this flag mirrors the server capability (matching the `twoFactor`
-     * convention). <SignIn/> gates the SSO affordance on `enabledMethods`, not on
-     * this flag, so the two never drift.
+     * Register the one thing that can actually settle the verdict: a session read
+     * with the token deliberately detached. The store holds the question and every
+     * fact bearing on it, and none of the network.
+     *
+     * Called the moment a token is captured with the verdict still unmeasured, and
+     * at registration if that already happened. Registration is what makes this
+     * work at all: a controller registers when a CLIENT is built, so the
+     * measurement no longer waits on a host app subscribing to the session store -
+     * which is a thing plenty of integrations never do, and every one of them used
+     * to keep a durable token for it.
+     *
+     * At most one measurer. A second registration replaces the first rather than
+     * joining it, because StrictMode double-invokes the memo that builds a client
+     * and two probes answer one question.
      */
-    sso: boolean;
+    measureWith(measure: () => void): void;
     /**
-     * JWT issuer (server contract CONTRACTS §8). Non-null only when the project's
-     * issuer toggle is on: exactly what a third-party verifier needs (Convex
-     * `auth.config.ts` = `{ type: "customJwt", issuer, jwks: jwksUrl,
-     * applicationID: aud, algorithm: "ES256" }`). The issuer remains stable when
-     * `authBaseUrl` follows a hosted or custom account-portal origin.
+     * Cut a receipt for a session read that is about to go out.
+     *
+     * A session read is answered asynchronously, and the session can be replaced
+     * while one is in flight - by a sign-in in THIS tab (`observe` runs inside the
+     * fetch decorator, while the store's post-mutation refresh only fires once the
+     * action resolves), or by one in ANOTHER tab, which lands in shared storage
+     * that this store holds no copy of. A read that started before either and
+     * comes back "no session" then describes a session that no longer exists, and
+     * acting on it wipes the token that just replaced it: a silent sign-out
+     * immediately after a successful sign-in, in whichever tab reloads first.
+     *
+     * The caller states no rule of its own. It cuts the receipt before dispatch
+     * and hands the answer back; deciding whether that answer still describes the
+     * session in play needs both the token and the lifecycle, and this is the only
+     * thing that has them.
      */
-    jwtIssuer: {
-        issuer: string;
-        jwksUrl: string;
-        aud: string;
-    } | null;
+    beginRead(): SessionRead;
     /**
-     * The bot challenge a project has configured, provider-agnostic.
+     * A session BEGINS here, before the request that mints it goes out.
      *
-     * Prefer this over the two Turnstile fields below, which predate provider
-     * choice and remain populated whenever the provider IS Turnstile.
+     * Called pre-dispatch at every minting door, because both facts it sets have
+     * to be true by the time the RESPONSE arrives: the verdict decides whether the
+     * request declares the transport at all (and an un-re-armed "cookies work"
+     * means it does not, so no token is ever minted), and `remember` decides where
+     * the token that comes back is written.
+     *
+     * It deliberately does NOT drop the token already held. Several minting doors
+     * run ON an existing session - the 2FA verifies upgrade a pending one, phone
+     * and email OTP verification can run signed in - so dropping the credential
+     * before dispatch would send the very request that needs it out anonymous. A
+     * failed attempt (a mistyped password at a re-auth prompt, a wrong OTP) would
+     * likewise sign the user out locally on exactly the browsers this exists for.
+     * The old token is replaced when the new one ARRIVES, which is the only moment
+     * the old session is actually over.
      */
-    captcha: CaptchaConfig | null;
-    /** Public Cloudflare Turnstile site key for the phone OTP challenge. */
-    turnstileSiteKey: string | null;
-    /** Public Cloudflare Turnstile site key for protected sign-up/sign-in actions. */
-    authTurnstileSiteKey: string | null;
-    locale: string;
-    badge: boolean;
-    configVersion: number;
+    beginSession(start: SessionStart): void;
+    /** Select the safer cookie-only path before a new session is minted. */
+    useCookieTransport(): void;
+    /** Drop a previous bearer only after its replacement cookie was delivered. */
+    completeCookieTransport(): void;
+    /** Select bearer delivery and remember which browser key the new token binds to. */
+    useBoundBearerTransport(thumbprint: string, keyIsPersistent: boolean): void;
+    /**
+     * A session ENDS here, unconditionally: this is sign-out, the one ending a
+     * response states plainly, and it means "end whatever is in play".
+     *
+     * Every other ending - expiry, a revoke from another device, the account
+     * deleted - is invisible in the response to the call that caused it and is
+     * caught instead by `SessionRead.endIfDead`, which has to establish that the
+     * ending is even about the session it is holding.
+     */
+    endSession(): void;
 };
+
+type TransportErrorKind = 'aborted' | 'timeout' | 'network' | 'response_too_large' | 'invalid_response';
+/**
+ * Stable, secret-safe failure from the shared HTTP boundary.
+ *
+ * Deliberately does not retain the request URL, headers, body, or underlying
+ * error. Server clients may carry secret authorization headers and hostile
+ * fetch implementations may echo those values in their error messages.
+ */
+declare class TransportError extends Error {
+    readonly kind: TransportErrorKind;
+    readonly requestId?: string;
+    constructor(kind: TransportErrorKind, requestId?: string);
+}
+declare const TRANSPORT_FETCH: unique symbol;
 /**
- * Fetch a project's public config. Publishable-key gated server-side; sent
- * without cookies (the payload is public, so no session is needed). Throws on a
- * non-2xx response so the caller can distinguish "config unavailable" from a
- * project that simply has a method disabled.
+ * A `fetch` that has been through the SDK's transport wiring - the ONLY thing
+ * this boundary will execute.
+ *
+ * The brand is a phantom: it exists purely so that `fetchImpl: fetch` and
+ * `fetchImpl: config.fetch ?? fetch` stop compiling. That is not pedantry, it is
+ * the bug this file has already shipped. The session transport lives in a
+ * decorator around `fetch` (see `session-transport.ts`), and the SDK had TWO
+ * sibling lines - `http.ts` and `http-client.ts` - each independently writing
+ * `config.fetch ?? fetch`. One got the decorator and the other did not, so the
+ * JWT issuer and the consent gate stayed broken on exactly the browsers the
+ * work existed to fix, with nothing failing anywhere to say so.
+ *
+ * A brand cannot stop a deliberate cast, and is not meant to. What it stops is
+ * the ACCIDENT: reaching this boundary now forces the author to name where the
+ * fetch came from, and there are only two answers - `config.fetch`, which
+ * carries the session, or `withoutSessionTransport(...)`, which says in one
+ * greppable word that this request has no session to carry.
+ *
+ * The brand is why `requestBoundedJson` can stay what it says it is - network
+ * mechanics, stateless, no idea what a session is - while still being the place
+ * a missing transport is caught.
  */
-declare function getPublicConfig(config: ResolvedAuthConfig): Promise<PublicConfig>;
+type TransportFetch = typeof fetch & {
+    readonly [TRANSPORT_FETCH]: true;
+};
 
 /** Legal-consent status for the signed-in user (server contract: `GET /consent`). */
 type ConsentStatus = {
@@ -468,6 +451,136 @@ interface AccountClient {
     delete(params?: DeleteAccountOptions, fetchOptions?: ActionFetchOptions): Promise<AuthActionResult<DeleteAccountData>>;
 }
 
+/**
+ * The organization invitation an emailed link is asking this browser to accept.
+ *
+ * The link lands on the TENANT'S OWN page carrying `?authowl_invitation=<id>`,
+ * and the only route that can redeem it needs a session the visitor usually does
+ * not have yet. So the id has to survive an entire sign-up or sign-in - which
+ * means surviving that flow's redirects: the OAuth round trip, the email
+ * verification round trip (which can land on a different page entirely), the MFA
+ * hold, and whatever navigation the operator's own `redirectTo` performs. A query
+ * parameter survives none of those, so it is read once, moved into storage, and
+ * taken out of the URL.
+ *
+ * Best-effort storage, deliberately: a browser that refuses `localStorage`
+ * degrades to "this invitation is claimable until you navigate", which is worse
+ * than the ideal and much better than a sign-in that throws.
+ */
+declare const INVITATION_QUERY_PARAM = "authowl_invitation";
+/**
+ * The only hint value that exists. There is deliberately no `existing_user`:
+ * absence has to stay ambiguous across an existing account, an older AuthOwl,
+ * and an account created between the invite and the click - so it can never be
+ * read as proof that an address IS registered.
+ */
+type InvitationRecipientHint = 'new_user';
+type InvitationClaim = {
+    id: string;
+    /** Epoch milliseconds, for age display and for expiring a forgotten claim. */
+    capturedAt: number;
+};
+/** Claims older than this are dropped unread: a month-old link is not a pending intent. */
+declare const INVITATION_CLAIM_MAX_AGE_MS: number;
+/**
+ * Read `?authowl_invitation` once, stash it, and strip it from the URL.
+ *
+ * Namespaced and only ours - a bare `invitation` belongs to the tenant's app as
+ * much as to us, and rewriting their parameters is not ours to do. Returns the
+ * captured claim, or the one already stashed when there is no parameter, so a
+ * caller can render from a single call.
+ */
+declare function captureInvitationClaim(now?: number): InvitationClaim | null;
+/** The stashed claim, or null when there is none, it is unreadable, or it is stale. */
+declare function readInvitationClaim(now?: number): InvitationClaim | null;
+declare function clearInvitationClaim(): void;
+
+/**
+ * Pure, dependency-free evaluators for an organization membership's advisory
+ * permission claim. Shared by the CLIENT `has()` (organization-client.ts, over
+ * the browser session) and the SERVER `has()` (server.ts, over a verified JWT),
+ * so the two paths can never disagree on what a membership grants.
+ *
+ * The membership carries the SAME `permissions` array AuthOwl emits into the
+ * session and the JWT claim (plan §4/§5): the relabelled `org:sys_*` system ids
+ * (plus their legacy bare forms during the dual-emit window) AND the operator's
+ * custom `org:<feature>:<action>` ids. Evaluation is a pure array/string check
+ * over that local claim - it NEVER calls a statement-only `/organization/has-
+ * permission` route, which only knows the 14 static statements and would wrongly
+ * report `false` for any custom permission.
+ */
+/** The active-membership shape carried on the session / decoded from a token. */
+interface OrganizationMembership {
+    /**
+     * The member's PRIMARY role key (built-in `owner`/`admin`/`member` or a
+     * project role). One value, for display - use {@link membershipHas} to gate,
+     * because a member can hold more than one.
+     */
+    role: string;
+    /**
+     * EVERY role the member holds, sorted. `member.role` is a comma-separated set
+     * server-side, so `admin,editor` is an ordinary membership - and gating on
+     * `role` alone made the others invisible.
+     *
+     * Optional because a token or session minted by an older AuthOwl carries only
+     * `role`; readers fall back to it rather than reporting a member holds nothing.
+     */
+    roles?: string[];
+    /**
+     * The member's effective permission ids: `org:sys_*` system claims (with
+     * their legacy bare forms during dual-emit) plus custom `org:<feature>:<action>`
+     * ids. Advisory only - the real boundary is server-side over the verified token.
+     */
+    permissions: string[];
+    /**
+     * Team ids the member holds inside the ACTIVE organization, as emitted by
+     * AuthOwl into both the session and the JWT claim. Teams are pure grouping:
+     * belonging to one grants nothing on its own, so this is for the application's
+     * own gating, never an authority check.
+     *
+     * Optional because a token minted before teams shipped carries no `teams` claim.
+     * `has({ teamId })` then returns false rather than guessing - it can only ever
+     * confirm a team the claim actually proves.
+     */
+    teams?: string[];
+}
+/** Clerk-style `has()` query: match the role, the permission, the team, or a combination (AND). */
+interface HasParams {
+    role?: string;
+    permission?: string;
+    /** Require membership of this team within the active organization. */
+    teamId?: string;
+}
+/** True when the membership's permission claim includes `permission`. Pure. */
+declare function membershipHasPermission(membership: OrganizationMembership | null | undefined, permission: string): boolean;
+/**
+ * True when the membership's team claim includes `teamId`. Pure.
+ *
+ * False when the claim carries no `teams` at all, which is what a token minted
+ * before teams shipped looks like - an absent claim is never read as "any team".
+ */
+declare function membershipHasTeam(membership: OrganizationMembership | null | undefined, teamId: string): boolean;
+/**
+ * Clerk-style `has()`: true when the membership satisfies EVERY provided
+ * criterion - the role matches AND the permission is included AND the team is
+ * held. Returns false when there is no membership, or when no criterion at all is
+ * given. Pure: no I/O, evaluated entirely against the local claim.
+ */
+/**
+ * True when the member holds `role` - as one of their roles, not merely as the
+ * primary one. Falls back to the primary when `roles` is absent, which is what a
+ * session or token from an older server carries.
+ */
+declare function membershipHasRole(membership: OrganizationMembership | null | undefined, role: string): boolean;
+declare function membershipHas(membership: OrganizationMembership | null | undefined, params: HasParams): boolean;
+/** Bind the pure evaluators to one membership (drives the client / hook `has`). */
+declare function createMembershipHas(membership: OrganizationMembership | null | undefined): {
+    has: (params: HasParams) => boolean;
+    hasPermission: (params: {
+        permission: string;
+    }) => boolean;
+};
+
 interface Organization {
     id: string;
     name: string;
@@ -961,7 +1074,7 @@ type AuthErrorContext = Readonly<AuthRequestContext & {
     failure: 'api' | 'aborted' | 'timeout' | 'network' | 'response_too_large' | 'invalid_response';
 }>;
 /** Stable AuthOwl policy codes that callers can handle without matching messages. */
-type AuthOwlErrorCode = 'MAU_BUDGET_REACHED' | 'BOT_CHALLENGE_FAILED' | 'VERSION_CONFLICT' | 'SESSION_NOT_FRESH' | 'ORGANIZATION_LAST_OWNER' | 'ORGANIZATION_NOT_FOUND' | 'MEMBER_NOT_FOUND' | 'INVITATION_NOT_FOUND' | 'EMAIL_VERIFICATION_REQUIRED_FOR_INVITATION' | 'EMAIL_VERIFICATION_REQUIRED_BEFORE_ACCEPTING_OR_REJECTING_INVITATION' | 'YOU_ARE_NOT_THE_RECIPIENT_OF_THE_INVITATION';
+type AuthOwlErrorCode = 'MAU_BUDGET_REACHED' | 'BOT_CHALLENGE_FAILED' | 'VERSION_CONFLICT' | 'SESSION_NOT_FRESH' | 'EMAIL_OTP_RECOVERY_DISABLED' | 'ORGANIZATION_LAST_OWNER' | 'ORGANIZATION_NOT_FOUND' | 'MEMBER_NOT_FOUND' | 'INVITATION_NOT_FOUND' | 'EMAIL_VERIFICATION_REQUIRED_FOR_INVITATION' | 'EMAIL_VERIFICATION_REQUIRED_BEFORE_ACCEPTING_OR_REJECTING_INVITATION' | 'YOU_ARE_NOT_THE_RECIPIENT_OF_THE_INVITATION';
 /** Framework-neutral reactive session snapshot. */
 interface SessionState {
     data: {
@@ -1587,4 +1700,137 @@ interface AuthOwlClient {
  */
 declare function createAuthOwlClient(config: ResolvedAuthConfig): AuthOwlClient;
 
-export { type EmailAuthData as $, type ActionFetchOptions as A, type AccountClient as B, type CreatePrivacyRightsRequestOptions as C, type AccountSession as D, type AccountStatusData as E, type AddOrganizationTeamMemberOptions as F, type AuthErrorContext as G, type AuthOwlErrorCode as H, type AuthRequestContext as I, type AuthResponseContext as J, type ChangeEmailOptions as K, type ChangePasswordData as L, type ChangePasswordOptions as M, type ConsentAcceptResult as N, type Organization as O, type PublicConfig as P, type ConsentStatus as Q, type RecordPrivacyConsentOptions as R, type SocialIdTokenOptions as S, type CreateOrganizationOptions as T, type CreateOrganizationTeamOptions as U, type DeleteAccountData as V, type DeleteAccountOptions as W, type DeleteOrganizationOptions as X, type DeletePasskeyData as Y, type DeletePasskeyOptions as Z, type DisableTwoFactorOptions as _, type AuthActionResult as a, type SendTwoFactorOtpOptions as a$, type EmailOtpAuthData as a0, type EmailOtpSignInOptions as a1, type EmailOtpType as a2, type EmailSignInOptions as a3, type EmailSignUpData as a4, type EmailSignUpOptions as a5, type EnableTwoFactorOptions as a6, type EnvironmentType as a7, type GenerateBackupCodesOptions as a8, type GetOrganizationInvitationOptions as a9, type OrganizationMember as aA, type OrganizationMemberUser as aB, type OrganizationMemberWithUser as aC, type OrganizationMembersData as aD, type OrganizationRoleSummary as aE, type OrganizationSelector as aF, type OrganizationTeam as aG, type OrganizationTeamMember as aH, type OrganizationUserInvitation as aI, type PasswordResetData as aJ, type PhoneAuthUser as aK, type PhoneOtpStartData as aL, type PhoneOtpStartOptions as aM, type PhoneOtpVerifyData as aN, type PhoneOtpVerifyOptions as aO, type RejectOrganizationInvitationData as aP, type RemoveOrganizationMemberData as aQ, type RemoveOrganizationMemberOptions as aR, type RemoveOrganizationTeamData as aS, type RemoveOrganizationTeamMemberData as aT, type RemoveOrganizationTeamMemberOptions as aU, type RemoveOrganizationTeamOptions as aV, type RequestPasswordResetOptions as aW, type ResetPasswordOptions as aX, type RevokeSessionOptions as aY, type SendOtpData as aZ, type SendTwoFactorOtpData as a_, type GetOrganizationOptions as aa, type GetToken as ab, type GetTokenOptions as ac, INVITATION_CLAIM_MAX_AGE_MS as ad, INVITATION_QUERY_PARAM as ae, type InvitationClaim as af, type InvitationRecipientHint as ag, type InviteOrganizationMemberOptions as ah, type JsonObject as ai, type JsonPrimitive as aj, type JsonValue as ak, type LeaveOrganizationOptions as al, type LinkSocialData as am, type LinkSocialOptions as an, type ListOrganizationInvitationsOptions as ao, type ListOrganizationMembersOptions as ap, type ListOrganizationRolesOptions as aq, type ListOrganizationTeamMembersOptions as ar, type ListOrganizationTeamsOptions as as, type MagicLinkData as at, type MagicLinkSignInOptions as au, type OrganizationFilterOperator as av, type OrganizationInvitation as aw, type OrganizationInvitationActionOptions as ax, type OrganizationInvitationDetails as ay, type OrganizationInvitationStatus as az, type AuthOwlClient as b, type SendVerificationOtpOptions as b0, type SetActiveTeamOptions as b1, type SignOutData as b2, type SocialAccount as b3, type SocialSignInOptions as b4, type TokenClient as b5, type TwoFactorBackupCodesData as b6, type TwoFactorEnableData as b7, type TwoFactorRedirectData as b8, type TwoFactorStatusData as b9, type TwoFactorVerifyData as ba, type UnlinkSocialOptions as bb, type UpdateOrganizationMemberRoleOptions as bc, type UpdateOrganizationOptions as bd, type UpdateOrganizationTeamOptions as be, type UpdatePasskeyData as bf, type UpdatePasskeyOptions as bg, type UpdateProfileOptions as bh, type UpdateUnsafeMetadataOptions as bi, type UserMetadata as bj, type UsernameSignInOptions as bk, type VerifyBackupCodeOptions as bl, type VerifyEmailOtpData as bm, type VerifyEmailOtpOptions as bn, type VerifyTotpOptions as bo, type VerifyTwoFactorOtpOptions as bp, type WaitlistJoinData as bq, type WaitlistJoinOptions as br, acceptConsent as bs, captureInvitationClaim as bt, clearInvitationClaim as bu, createAuthOwlClient as bv, createTokenClient as bw, getConsentStatus as bx, readInvitationClaim as by, type PasskeySignInOptions as c, type PasskeyAuthData as d, type AddPasskeyOptions as e, type AuthPasskey as f, type AuthClientError as g, type AuthSession as h, type AuthUser as i, type OrganizationClient as j, type OrganizationDetails as k, type PrivacyClient as l, type PrivacyConsentPreference as m, type PrivacyConsentState as n, type PrivacyLocale as o, type PrivacyRightState as p, type PrivacyRightType as q, type PrivacyRightsRequest as r, type SessionState as s, type SessionStore as t, type SetActiveOrganizationOptions as u, type SocialAuthData as v, getPublicConfig as w, type PhoneOtpChallengeData as x, type AkedlyShieldStartProof as y, type AcceptOrganizationInvitationData as z };
+/**
+ * A framework adapter's supported view of the browser session transport.
+ *
+ * `authenticatedFetch` is the exact fetch owned by the resolved core client,
+ * so out-of-band requests inherit the current cookie/bearer verdict and sender
+ * proof. The lifecycle contains no credential or response data.
+ */
+type SessionTransportConnection = Readonly<{
+    authenticatedFetch: TransportFetch;
+    sessionStore: SessionStore;
+    subscribeLifecycle(listener: (event: SessionLifecycleEvent) => void): () => void;
+}>;
+type SessionTransportIntegration = Readonly<{
+    connect(connection: SessionTransportConnection): void;
+    /** Project a newly established AuthOwl session before its action resolves. */
+    sessionEstablished(): Promise<void>;
+    /** Remove the framework-owned projection before sign-out resolves. */
+    sessionEnded(): Promise<void>;
+}>;
+/** Attach a framework integration to the fetch it asks the core client to use. */
+declare function withSessionTransportIntegration(fetchImpl: typeof fetch, integration: SessionTransportIntegration): typeof fetch;
+
+/**
+ * The session, attached to a request and harvested off a response, in ONE place.
+ *
+ * BOTH CARGOES, NO SECOND WIRE. The sign-in challenge - the `two_factor` ticket
+ * and the `dont_remember` flag - travels on this same transport, and it needed
+ * not one line here: `declareOn` and `observe` below each carry both, so a
+ * request that gets the session gets the challenge by construction. That is
+ * deliberate rather than incidental. Wiring the challenge at the call sites that
+ * know about 2FA is precisely the bug class this file exists to make
+ * unrepresentable - a door that gets one cargo and not the other - and the
+ * server's own ingress is built the same way for the same reason
+ * (`bearerTransportHeaders` does both translations in one function, and the
+ * headers it returns are obtainable nowhere else, so no door can opt into the
+ * session half and forget the challenge half). See `session-challenge.ts`.
+ *
+ * WHY THIS IS A `fetch` DECORATOR AND NOT A STEP IN A CLIENT
+ *
+ * Because this SDK used to reach the network through two independent doors and
+ * the first version of this transport wired one and missed the other. See
+ * `TransportFetch` in `transport.ts`, which owns that incident and the guard it
+ * produced.
+ *
+ * The doors have since been collapsed into one (`requestPublishableJson`), but
+ * the session does not ride THAT, because a door is a thing somebody can add.
+ * It rides the `fetch`, which no door can make a request without, and the brand
+ * on `TransportFetch` makes an undecorated one refuse to typecheck at the one
+ * boundary every request passes through. A deliberate opt-out still compiles and
+ * is meant to; what the brand removes is the SILENT version, where a client
+ * somebody added simply never carries the session and nothing anywhere says so.
+ *
+ * `resolveConfig` is the single producer: `config.fetch` is ALWAYS the decorated
+ * fetch, wrapped around the host's if one was supplied. There is no undecorated
+ * fetch left on a resolved config to reach for by mistake.
+ */
+
+/**
+ * Everything about this project's session that is NOT the ordinary fetch.
+ *
+ * Handed to the session controller directly rather than looked up from a project
+ * id. The controller used to take that id and use it as BOTH the token store's
+ * key and a BroadcastChannel name, which is only correct while the two strings
+ * are the same string: pass a channel name and the controller silently measures
+ * a private, permanently empty store. Two facts, two parameters.
+ */
+type SessionBinding = {
+    /**
+     * The same transport with the session deliberately DETACHED - no token, no
+     * challenge, no declaration, cookies only.
+     *
+     * Exactly one caller: the probe that measures whether this browser keeps our
+     * cross-site cookie. Every other request attaches the token when we hold one,
+     * which would make a session read succeed whether or not the cookie survived,
+     * and the SDK would never learn the difference.
+     */
+    readonly probe: TransportFetch;
+    /** The store the fetch above attaches from, and the lifecycle the doors drive. */
+    readonly tokens: SessionTokenStore;
+    /** Framework adapter registered on the caller-supplied fetch, when present. */
+    readonly integration?: SessionTransportIntegration | null;
+    /** Decide cookie-only or sender-bound bearer transport before a session mint. */
+    prepareSession(start: SessionStart): Promise<void>;
+};
+
+type AuthConfig = {
+    publishableKey: string;
+    apiUrl: string;
+    /** Optional fetch override (e.g. for testing). */
+    fetch?: typeof fetch;
+};
+type ResolvedAuthConfig = Omit<AuthConfig, 'fetch'> & {
+    decoded: DecodedPublishableKey;
+    /** Fully-resolved base URL pointing at the per-project auth endpoint. */
+    projectBaseURL: string;
+    /**
+     * THE fetch for this project - the caller's, wrapped in the session transport.
+     *
+     * Required rather than optional, and branded, so that `config.fetch ?? fetch`
+     * cannot be written at all. See `TransportFetch` in `transport.ts` for what
+     * the brand buys and which bug it closes.
+     */
+    fetch: TransportFetch;
+    /**
+     * The session itself, resolved here because this function is the only producer
+     * of the fetch that carries it. Nothing else has to find the store by id, and
+     * no request boundary has to grow a "but not this one" flag to reach the
+     * detached fetch.
+     *
+     * A BROWSER SIGN-IN FLOW MUST GO THROUGH A CONSTRUCTED CLIENT, not through
+     * `config.fetch` directly. Resolving a config builds the token store, but the
+     * thing that SETTLES its cookie verdict is registered by the session
+     * controller a client builds - so a hand-rolled integration that drives sign-in
+     * off this fetch captures a token nothing will ever measure. The token is then
+     * held in memory and never written, and the session dies at the next reload on
+     * exactly the browsers this transport exists for. Every shipped surface
+     * (`createAuthOwlClient`, the native client, the React provider) builds one;
+     * this note is for anyone reaching below them. Moving the measurement onto
+     * this binding is the queued fix that removes the hazard rather than
+     * documenting it.
+     */
+    session: SessionBinding;
+};
+type ResolvedAuthTarget = Readonly<{
+    publishableKey: string;
+    apiUrl: string;
+    decoded: DecodedPublishableKey;
+    projectBaseURL: string;
+}>;
+/** Resolve the shared, side-effect-free project endpoint contract. */
+declare function resolveAuthTarget(input: Pick<AuthConfig, 'publishableKey' | 'apiUrl'>): ResolvedAuthTarget;
+declare function resolveConfig(input: AuthConfig): ResolvedAuthConfig;
+
+export { type DeleteAccountData as $, type ActionFetchOptions as A, resolveConfig as B, type CreatePrivacyRightsRequestOptions as C, type DecodedPublishableKey as D, type PhoneOtpChallengeData as E, type AkedlyShieldStartProof as F, type AcceptOrganizationInvitationData as G, type HasParams as H, type AccountClient as I, type AccountSession as J, type AccountStatusData as K, type AddOrganizationTeamMemberOptions as L, type AuthErrorContext as M, type AuthOwlErrorCode as N, type Organization as O, type PasskeySignInOptions as P, type AuthRequestContext as Q, type ResolvedAuthConfig as R, type SocialIdTokenOptions as S, type AuthResponseContext as T, type ChangeEmailOptions as U, type ChangePasswordData as V, type ChangePasswordOptions as W, type ConsentAcceptResult as X, type ConsentStatus as Y, type CreateOrganizationOptions as Z, type CreateOrganizationTeamOptions as _, type AuthActionResult as a, type RequestPasswordResetOptions as a$, type DeleteAccountOptions as a0, type DeleteOrganizationOptions as a1, type DeletePasskeyData as a2, type DeletePasskeyOptions as a3, type DisableTwoFactorOptions as a4, type EmailAuthData as a5, type EmailOtpAuthData as a6, type EmailOtpSignInOptions as a7, type EmailOtpType as a8, type EmailSignInOptions as a9, type OrganizationFilterOperator as aA, type OrganizationInvitation as aB, type OrganizationInvitationActionOptions as aC, type OrganizationInvitationDetails as aD, type OrganizationInvitationStatus as aE, type OrganizationMember as aF, type OrganizationMemberUser as aG, type OrganizationMemberWithUser as aH, type OrganizationMembersData as aI, type OrganizationRoleSummary as aJ, type OrganizationSelector as aK, type OrganizationTeam as aL, type OrganizationTeamMember as aM, type OrganizationUserInvitation as aN, type PasswordResetData as aO, type PhoneAuthUser as aP, type PhoneOtpStartData as aQ, type PhoneOtpStartOptions as aR, type PhoneOtpVerifyData as aS, type PhoneOtpVerifyOptions as aT, type RejectOrganizationInvitationData as aU, type RemoveOrganizationMemberData as aV, type RemoveOrganizationMemberOptions as aW, type RemoveOrganizationTeamData as aX, type RemoveOrganizationTeamMemberData as aY, type RemoveOrganizationTeamMemberOptions as aZ, type RemoveOrganizationTeamOptions as a_, type EmailSignUpData as aa, type EmailSignUpOptions as ab, type EnableTwoFactorOptions as ac, type GenerateBackupCodesOptions as ad, type GetOrganizationInvitationOptions as ae, type GetOrganizationOptions as af, type GetToken as ag, type GetTokenOptions as ah, INVITATION_CLAIM_MAX_AGE_MS as ai, INVITATION_QUERY_PARAM as aj, type InvitationClaim as ak, type InvitationRecipientHint as al, type InviteOrganizationMemberOptions as am, type JsonObject as an, type JsonPrimitive as ao, type JsonValue as ap, type LeaveOrganizationOptions as aq, type LinkSocialData as ar, type LinkSocialOptions as as, type ListOrganizationInvitationsOptions as at, type ListOrganizationMembersOptions as au, type ListOrganizationRolesOptions as av, type ListOrganizationTeamMembersOptions as aw, type ListOrganizationTeamsOptions as ax, type MagicLinkData as ay, type MagicLinkSignInOptions as az, type AuthOwlClient as b, type ResetPasswordOptions as b0, type ResolvedAuthTarget as b1, type RevokeSessionOptions as b2, type SendOtpData as b3, type SendTwoFactorOtpData as b4, type SendTwoFactorOtpOptions as b5, type SendVerificationOtpOptions as b6, type SessionLifecycleEvent as b7, type SessionTransportConnection as b8, type SessionTransportIntegration as b9, type VerifyTwoFactorOtpOptions as bA, type WaitlistJoinData as bB, type WaitlistJoinOptions as bC, acceptConsent as bD, captureInvitationClaim as bE, clearInvitationClaim as bF, createAuthOwlClient as bG, createTokenClient as bH, getConsentStatus as bI, membershipHas as bJ, membershipHasPermission as bK, membershipHasRole as bL, membershipHasTeam as bM, readInvitationClaim as bN, resolveAuthTarget as bO, withSessionTransportIntegration as bP, type SetActiveTeamOptions as ba, type SignOutData as bb, type SocialAccount as bc, type SocialSignInOptions as bd, type TokenClient as be, TransportError as bf, type TransportErrorKind as bg, type TwoFactorBackupCodesData as bh, type TwoFactorEnableData as bi, type TwoFactorRedirectData as bj, type TwoFactorStatusData as bk, type TwoFactorVerifyData as bl, type UnlinkSocialOptions as bm, type UpdateOrganizationMemberRoleOptions as bn, type UpdateOrganizationOptions as bo, type UpdateOrganizationTeamOptions as bp, type UpdatePasskeyData as bq, type UpdatePasskeyOptions as br, type UpdateProfileOptions as bs, type UpdateUnsafeMetadataOptions as bt, type UserMetadata as bu, type UsernameSignInOptions as bv, type VerifyBackupCodeOptions as bw, type VerifyEmailOtpData as bx, type VerifyEmailOtpOptions as by, type VerifyTotpOptions as bz, type PasskeyAuthData as c, type AddPasskeyOptions as d, type AuthPasskey as e, type AuthConfig as f, type AuthClientError as g, type AuthSession as h, type AuthUser as i, type OrganizationClient as j, type OrganizationDetails as k, type OrganizationMembership as l, type PrivacyClient as m, type PrivacyConsentPreference as n, type PrivacyConsentState as o, type PrivacyLocale as p, type PrivacyRightState as q, type PrivacyRightType as r, type PrivacyRightsRequest as s, type RecordPrivacyConsentOptions as t, type SessionState as u, type SessionStore as v, type SetActiveOrganizationOptions as w, type SocialAuthData as x, createMembershipHas as y, decodePublishableKey as z };