@authowl/core 0.13.0 → 0.15.0

package/dist/organization-membership--eTrgk_L.d.cts

@@ -0,0 +1,442 @@
+type DecodedPublishableKey = {
+    prefix: 'pk_live' | 'pk_test';
+    env: 'live' | 'test';
+    projectId: string;
+};
+declare function decodePublishableKey(key: string): DecodedPublishableKey;
+
+/**
+ * The exact session-cookie name the auth server sets for a given project.
+ *
+ * Single source of truth for the cookie name across the SDK. The server
+ * (the AuthOwl server project factory) configures
+ * `advanced.cookiePrefix = "p_" + <projectId without dashes>` and
+ * `useSecureCookies` in production; the auth engine then names the session
+ * cookie `${securePrefix}${cookiePrefix}.session_token`, where `securePrefix`
+ * is `__Secure-` for secure cookies and empty otherwise:
+ *
+ *   dev  (http):  p_<idNoDashes>.session_token
+ *   prod (https): __Secure-p_<idNoDashes>.session_token
+ *
+ * Verified 2026-07-06 against the auth engine's `getCookies()` with the server's
+ * real config (see CONTRACTS section 5 and `cookie.test.ts`). Note the engine
+ * joins the prefix and name with a dot (`.`), not an underscore, and uses the
+ * `__Secure-` (not `__Host-`) prefix - both are easy to get wrong by hand, and
+ * getting them wrong makes `auth()` forward a cookie the server never set. If an
+ * auth-engine upgrade changes cookie naming, re-verify and update this function,
+ * the `cookie.test.ts` fixtures, and CONTRACTS section 5 together.
+ *
+ * `secure` must reflect the SERVER's cookie mode: callers holding the auth API
+ * URL derive it from the protocol (`https:` => secure). Callers that cannot
+ * know it (the UX-only redirect middleware) should check both variants.
+ */
+declare function sessionCookieName(projectId: string, opts?: {
+    secure?: boolean;
+}): string;
+
+/** 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;
+};
+/**
+ * One session read, from the moment it is dispatched to the moment it answers.
+ *
+ * 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.
+ */
+type SessionRead = {
+    /**
+     * 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.
+     */
+    readonly carriedToken: boolean;
+    /**
+     * 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.
+     */
+    endIfDead(): void;
+    /**
+     * 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.
+     */
+    recordCookieVerdict(cookiesWork: boolean): void;
+};
+type SessionTokenStore = {
+    /**
+     * 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.
+     */
+    hasToken(): boolean;
+    /**
+     * 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.
+     */
+    declareOn(headers: Headers): boolean;
+    /**
+     * 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.
+     */
+    wantsToken(): boolean;
+    /** Whether this browser's cookie behaviour is still unmeasured. */
+    needsProbe(): boolean;
+    /**
+     * 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.
+     */
+    observe(headers: Headers): void;
+    /**
+     * 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.
+     */
+    dropChallenge(): void;
+    /**
+     * 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.
+     */
+    measureWith(measure: () => void): void;
+    /**
+     * 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.
+     */
+    beginRead(): SessionRead;
+    /**
+     * A session BEGINS here, before the request that mints it goes out.
+     *
+     * 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.
+     */
+    beginSession(start: SessionStart): 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;
+/**
+ * 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.
+ */
+type TransportFetch = typeof fetch & {
+    readonly [TRANSPORT_FETCH]: true;
+};
+
+/**
+ * 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;
+};
+
+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;
+};
+declare function resolveConfig(input: AuthConfig): ResolvedAuthConfig;
+
+/**
+ * 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 canonical role key (built-in `owner`/`admin`/`member` or a project role). */
+    role: 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.
+ */
+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;
+};
+
+export { type AuthConfig as A, type DecodedPublishableKey as D, type HasParams as H, type OrganizationMembership as O, type ResolvedAuthConfig as R, TransportError as T, type TransportErrorKind as a, membershipHasPermission as b, createMembershipHas as c, decodePublishableKey as d, membershipHasTeam as e, membershipHas as m, resolveConfig as r, sessionCookieName as s };