@ikonai/sdk-react-ui 1.3.0 → 1.3.2

package/app/use-ikon-app.d.ts

@@ -28,6 +28,14 @@ declare global {
  * Module registration function type.
  */
 export type IkonUiModuleRegistration = (registry: IkonUiRegistry) => void;
+/**
+ * Connect parameters for one session: the query string, then whatever the app resolved itself.
+ *
+ * The app wins on a shared key. An app derives its parameters from something the visitor does not
+ * control — the hostname it was served on, a build-time flag — and those choices decide which
+ * SessionIdentity the connect resolves to, so a hand-typed query parameter must not displace one.
+ */
+export declare function mergeConnectParameters(urlParameters: Record<string, string>, appParameters?: Record<string, string>): Record<string, string>;
 /**
  * Options for the useIkonApp hook.
  */
@@ -43,6 +51,18 @@ export interface UseIkonAppOptions {
      * modules: [registerStandardUiModule]
      */
     modules?: IkonUiModuleRegistration[];
+    /**
+     * Connect parameters the app supplies itself, merged over the ones parsed from the URL.
+     *
+     * They reach the app twice: as the `params` the backend hashes into SessionIdentity, and as
+     * `Context.Parameters` on each client. Without this, the only way to steer SessionIdentity is to
+     * put a value in the address bar — which a frontend deriving state from its own environment (the
+     * hostname it was served on, a build-time flag) cannot do without rewriting the URL.
+     *
+     * App-supplied keys win over the same key in the query string, so a hand-typed parameter cannot
+     * override what the app resolved.
+     */
+    parameters?: Record<string, string>;
     /**
      * Timeout configuration passed to IkonClient.
      * If not provided, SDK defaults are used.

package/auth/auth-service.d.ts

@@ -1,5 +1,5 @@
 import { AuthenticationResponseJSON, PublicKeyCredentialCreationOptionsJSON, PublicKeyCredentialRequestOptionsJSON, RegistrationResponseJSON } from '@simplewebauthn/browser';
-import { AuthSession, LoginMethod } from './types';
+import { AuthSession, LoginMethod, RefreshableSession } from './types';
 /**
  * Result of parsing an OAuth callback from the URL.
  */
@@ -54,6 +54,31 @@ export declare function verifyLoginCode({ email, code, authUrl }: VerifyLoginCod
  * Returns the token and provider if present, or null if not an OAuth callback.
  */
 export declare function parseOAuthCallback(): OAuthCallbackResult | null;
+/** The single-use code an opted-in callback carries, waiting to be exchanged for a session. */
+export declare function parseOAuthCodeCallback(): {
+    code: string;
+    provider: LoginMethod;
+} | null;
+/**
+ * Trades the callback's code for the session it stands for, using the verifier this browser kept.
+ *
+ * A missing verifier is a real failure rather than something to paper over: it means this is not
+ * the browser (or not the tab) that started the sign-in — which is exactly the case PKCE exists to
+ * refuse — so the caller reports a failed sign-in instead of silently leaving the visitor
+ * anonymous with a code still in the address bar.
+ */
+export declare function exchangeOAuthCode(code: string, provider: LoginMethod, authUrlOverride?: string): Promise<AuthSession>;
+/**
+ * Renews the access token from the refresh cookie. Returns null when the session is definitively
+ * over — the chain was spent, revoked, or never existed — and throws when the answer is simply
+ * unknown, so a caller can tell "signed out" from "the network is down" and only act on the first.
+ *
+ * Deliberately not routed through `authFetch`. The cookie is issued only when the exchange was
+ * answered same-origin, so the same-origin base is the only one that can hold it; authFetch's
+ * cross-origin fallback would send a cookie-less renewal to the shared auth host, take the 401 for
+ * a dead session, and sign out someone whose session was never in trouble.
+ */
+export declare function refreshBrowserSession(marker: RefreshableSession): Promise<AuthSession | null>;
 /**
  * Sign-in failure parsed from an OAuth callback redirect: the machine code from the `error` query
  * param, plus the provider the callback names when it knows which one failed.
@@ -98,7 +123,7 @@ export declare function clearOAuthParams(): void;
 /**
  * Build an OAuth redirect URL for the given provider.
  */
-export declare function buildOAuthRedirectUrl(provider: LoginMethod, spaceId: string, authUrl: string, returnUrl?: string): string;
+export declare function buildOAuthRedirectUrl(provider: LoginMethod, spaceId: string, authUrl: string, returnUrl?: string): Promise<string>;
 /**
  * Check if passkey/WebAuthn is supported in the current browser.
  */
@@ -119,3 +144,13 @@ export declare function getPasskeyAuthenticationOptions(authUrl: string, email?:
  * Verify passkey authentication with the auth service.
  */
 export declare function verifyPasskeyAuthentication(authUrl: string, response: AuthenticationResponseJSON): Promise<AuthSession>;
+/**
+ * Ends the session on the server as well as locally, so a copy of the token taken from the URL or
+ * from storage stops working instead of outliving the sign-out by up to a week.
+ *
+ * Best effort by design: logging out must succeed even offline, against an older backend with no
+ * such route, or when the request is simply slow. The local session is cleared by the caller
+ * regardless — a client that cannot reach the server ends up exactly where it was before this
+ * existed, which is also where app bundles shipping an older SDK copy stay.
+ */
+export declare function revokeSessionOnServer(token: string, authUrlOverride?: string): Promise<void>;

package/auth/index.d.ts

@@ -1,5 +1,6 @@
 export type { AuthConfig, AuthContextValue, AuthSession, AuthState, AuthUser, LoginMethod } from './types';
 export { clearAuthSession, isSignedInBootLikely, loadAuthSession, saveAuthSession, sessionToUser } from './storage';
-export { authenticateAnonymous, buildOAuthRedirectUrl, clearOAuthParams, describeAuthError, getPasskeyAuthenticationOptions, getPasskeyRegistrationOptions, isPasskeySupported, parseOAuthCallback, parseOAuthError, sendLoginCode, verifyLoginCode, verifyPasskeyAuthentication, verifyPasskeyRegistration, type OAuthCallbackResult, type OAuthErrorResult, type SendLoginCodeOptions, type VerifyLoginCodeOptions, } from './auth-service';
+export { authenticateAnonymous, buildOAuthRedirectUrl, clearOAuthParams, describeAuthError, exchangeOAuthCode, getPasskeyAuthenticationOptions, getPasskeyRegistrationOptions, isPasskeySupported, parseOAuthCallback, parseOAuthCodeCallback, parseOAuthError, revokeSessionOnServer, sendLoginCode, verifyLoginCode, verifyPasskeyAuthentication, verifyPasskeyRegistration, type OAuthCallbackResult, type OAuthErrorResult, type SendLoginCodeOptions, type VerifyLoginCodeOptions, } from './auth-service';
 export { AuthProvider, useAuth, useAuthOptional, type AuthProviderProps } from './auth-context';
 export { useAuthGuard, type UseAuthGuardOptions, type UseAuthGuardResult } from './use-auth-guard';
+export { OAUTH_CONTINUE_PARAM, captureOAuthContinuation, completeOAuthContinuation, hasPendingOAuthContinuation } from './oauth-continuation';

package/auth/oauth-continuation.d.ts

@@ -0,0 +1,36 @@
+/** What `/ikon/oauth/authorize` puts on the app's own URL when it sends the browser here to sign in. */
+export declare const OAUTH_CONTINUE_PARAM = "ikon-oauth";
+/**
+ * The app-rendered half of a space's OAuth flow.
+ *
+ * `/authorize` cannot show a sign-in screen itself — the app owns that screen, its methods and its
+ * branding, and the person is being asked to grant access to *this app*, so this app is what they should
+ * be looking at while they decide. So it parks the request and bounces the browser back here with a
+ * pointer to it; the SDK raises the login prompt it already has; and a completed sign-in reports back.
+ *
+ * The pointer is kept in BOTH the URL and sessionStorage until the flow ends, and that redundancy is
+ * the point. Signing in with an external provider hands the browser to another origin and back, and
+ * what comes back is not always the same browsing context — a popup, a reopened tab, a session-storage
+ * partition we did not choose. Storage alone lost the pointer in exactly that case, and because the
+ * param had already been stripped there was nothing left to recover it from: the authorization sat
+ * parked, the client waited for a code forever, and the user saw an ordinary app with no sign of it.
+ *
+ * The URL copy is what survives, because the sign-in return URL is built from the current location.
+ * That is safe here for a reason this flow states explicitly elsewhere: the pointer is NOT a
+ * credential. It names a parked authorization, and the user binding is made server-side from the
+ * session token posted below, so a copied or referrer-leaked pointer authorizes nobody. It is cleared
+ * from both places the moment the flow finishes or fails.
+ */
+export declare function captureOAuthContinuation(): boolean;
+export declare function hasPendingOAuthContinuation(): boolean;
+/**
+ * Report the completed sign-in and hand the browser to the consent screen.
+ *
+ * Only ever called after a REAL sign-in — `useAuthGuard` treats an anonymous session as not satisfying a
+ * prompt, which is the guest/global exclusion this flow needs and already had. A `global` visitor is one
+ * shared space-wide user, so authorizing as one would hand every client the same identity.
+ *
+ * Failure clears the pointer and returns false: the app then carries on as a normally signed-in session
+ * rather than trapping the user in a flow that cannot finish.
+ */
+export declare function completeOAuthContinuation(): Promise<boolean>;

package/auth/storage.d.ts

@@ -1,4 +1,4 @@
-import { AuthSession, AuthUser } from './types';
+import { AuthSession, AuthUser, RefreshableSession } from './types';
 /**
  * Check whether a JWT token has expired by decoding its `exp` claim.
  * Returns true when the token is expired or cannot be decoded.
@@ -13,6 +13,30 @@ export declare function saveAuthSession(session: AuthSession): void;
  * Returns null if no session exists or if the session has expired.
  */
 export declare function loadAuthSession(): AuthSession | null;
+/**
+ * Record that this browser has a refresh cookie behind the given sign-in. Replaces the stored
+ * session rather than joining it: the two describe the same thing, and a leftover token record
+ * would be preferred over the live one on the next load.
+ */
+export declare function saveRefreshableSession(session: RefreshableSession): void;
+/**
+ * The refresh-cookie marker, or null when there is none or it is old enough that the cookie behind
+ * it has certainly expired. Dropping a stale one is what stops a long-abandoned browser starting
+ * every load with a renewal that cannot succeed.
+ */
+export declare function loadRefreshableSession(): RefreshableSession | null;
+/** Move the marker's renewal stamp forward, mirroring the cookie the server just replaced. */
+export declare function touchRefreshableSession(): void;
+export declare function clearRefreshableSession(): void;
+/**
+ * Drop a stored anonymous session — token record and refresh marker alike.
+ *
+ * For an app whose sign-in wall offers no not-signed-in entry. Such a session can only date from a
+ * time when one was offered, or from another app sharing the origin, and it must not be what walks
+ * a visitor through the wall. Discarded rather than ignored: a session the app will not honour has
+ * no business leaving a usable token in storage.
+ */
+export declare function discardAnonymousSession(): void;
 /**
  * Pre-auth heuristic for "this load will connect as a signed-in user": a stored non-anonymous
  * session, or an OAuth callback in flight (the provider just redirected back with `ikon_token` in

package/auth/types.d.ts

@@ -15,6 +15,12 @@ export interface AuthUser {
     provider: LoginMethod | 'anonymous' | 'dev';
     token: string;
     authenticatedAt: number;
+    /**
+     * When {@link token} stops being accepted, for the sign-ins whose token is short-lived enough to
+     * need renewing before then. Absent on the long-lived tokens, which are simply used until they
+     * expire.
+     */
+    expiresAt?: string;
 }
 /**
  * Authentication state.
@@ -64,6 +70,19 @@ export interface AuthSession {
     token: string;
     provider: LoginMethod | 'anonymous' | 'dev';
     authenticatedAt: number;
+    /** Set when the token is short-lived and a refresh cookie stands behind it. */
+    expiresAt?: string;
+}
+/**
+ * What is persisted for a sign-in whose access token is NOT persisted: enough to know on the next
+ * load that a session exists and whose it is, and nothing that can be used as a credential.
+ */
+export interface RefreshableSession {
+    provider: LoginMethod | 'anonymous' | 'dev';
+    /** When the person actually signed in. Unchanged by renewals — those renew a token, not a login. */
+    authenticatedAt: number;
+    /** Last successful renewal, which is what the cookie's own lifetime runs from. */
+    renewedAt: number;
 }
 /**
  * Auth context value returned by useAuth hook.

package/auth/use-auth-guard.d.ts

@@ -37,6 +37,13 @@ export interface UseAuthGuardResult {
      * Dismiss an on-demand login prompt and return to the app. No effect on a hard sign-in wall.
      */
     dismissLoginPrompt: () => void;
+    /**
+     * Why the prompt was raised, when whoever raised it said. Render it: a sign-in screen that appears
+     * without explanation is one a person cannot judge. Someone sent here by an application asking to
+     * act on their behalf needs to know that is what they are agreeing to before they choose an account,
+     * not after.
+     */
+    loginPromptReason: string | null;
 }
 /**
  * Headless hook for route protection logic.