@ikonai/sdk-react-ui 1.2.0 → 1.3.1

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.
@@ -122,6 +142,12 @@ export interface UseIkonAppResult {
      * say the session has ended rather than show a generic connection error.
      */
     isSessionExpired: boolean;
+    /**
+     * True when the app's server started and then died before it could serve the session — nearly
+     * always an exception out of the app's own startup code. Terminal: the same bundle crashes the
+     * same way, so the app should say it failed to start instead of waiting out the connect budget.
+     */
+    isStartupFailed: boolean;
     /**
      * UI stores for rendering.
      */

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.
  */
@@ -7,6 +7,17 @@ export interface OAuthCallbackResult {
     token: string;
     provider: LoginMethod;
 }
+/**
+ * Whether a same-origin auth response came from an LB with no `/ikon/auth` route — the app
+ * frontend answered instead of the auth service.
+ *
+ * The marker header settles it outright when present. The shape heuristic below is the fallback
+ * for an auth service deployed before the header existed, and it can only ever guess: it reads a
+ * 404/405 or an HTML 200 as the app frontend answering. That guess has misfired twice on
+ * /email/send's 204 — Express stamps its default text/html content type even on a bodyless
+ * response — which is why an HTML content type counts only together with a 200.
+ */
+export declare function isRouteMissingResponse(response: Response): boolean;
 /**
  * Authenticate anonymously with the Ikon auth service.
  * Returns a session with a token for anonymous users. `flavor` names which not-signed-in identity
@@ -43,18 +54,76 @@ 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.
+ */
+export interface OAuthErrorResult {
+    code: string;
+    provider: LoginMethod | null;
+}
 /**
  * Get the error from an OAuth callback if present.
  */
-export declare function parseOAuthError(): string | null;
+export declare function parseOAuthError(): OAuthErrorResult | null;
 /**
- * Clear OAuth-related parameters from the URL.
+ * True when the URL asks this tab to skip the local-dev auto-login (`?ikon-signed-out`).
+ *
+ * A local `ikon app run` signs the developer straight in, which is what you want while building —
+ * and exactly what you cannot have while checking the signed-out product. Without this, seeing the
+ * public site means logging out by hand in a throwaway browser profile, so it tends not to happen
+ * and the guest experience ships unlooked-at. Local dev only: it suppresses the injected developer
+ * token and nothing else, so it grants no access and does nothing in a deployed build.
+ */
+export declare function wantsSignedOut(): boolean;
+/**
+ * Human-readable text for an OAuth callback error code. Unknown codes pass through verbatim so a
+ * backend code this build does not know yet still surfaces rather than disappearing.
+ *
+ * The refused-link text is written for the visitor's mental model, not the system's: they clicked
+ * the provider because they have an account THERE, so it must say the pre-existing account is on
+ * this app, must not sound like their provider account is broken, and must point at a concrete
+ * next step — the email code sign-in when this app offers it, since that proves mailbox ownership
+ * and reaches the existing account.
+ */
+export declare function describeAuthError(code: string, provider?: string | null, options?: {
+    emailSignInAvailable?: boolean;
+}): string;
+/**
+ * Clear OAuth-related parameters from the URL, preserving the app's own query parameters —
+ * a deep link like /projects/new?prompt=… must survive the OAuth round-trip so the app can
+ * read it after sign-in (the SDK sends path+query as the connect InitialPath).
  */
 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.
  */
@@ -75,3 +144,32 @@ 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>;
+/**
+ * True when this document is nested in another. A sign-in cannot be a same-tab redirect here: the
+ * provider's consent screen sets X-Frame-Options and would simply refuse to paint.
+ *
+ * A cross-origin parent makes the property access itself throw, which is the embedded case too.
+ */
+export declare function isEmbedded(): boolean;
+/**
+ * Run the OAuth sign-in in a popup and resolve with the code it comes back with.
+ *
+ * The popup goes to the auth host directly rather than through an app's same-origin auth proxy: it
+ * is a top-level window, so there is no CORS to avoid, and the return has to land on the auth
+ * origin — the one origin that is allowed for every app, whatever address the app itself is on.
+ * The verifier for the code stays in THIS document, so the exchange must also happen here.
+ */
+export declare function runOAuthPopup(provider: LoginMethod, spaceId: string): Promise<{
+    code: string;
+    provider: LoginMethod;
+}>;

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, getPasskeyAuthenticationOptions, getPasskeyRegistrationOptions, isPasskeySupported, parseOAuthCallback, parseOAuthError, sendLoginCode, verifyLoginCode, verifyPasskeyAuthentication, verifyPasskeyRegistration, type OAuthCallbackResult, 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,28 @@
+/** 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 stashed in sessionStorage rather than left in the URL because signing in with an
+ * external provider navigates away and back, which is the same reason the pending-call handoff exists.
+ * It is not a credential: it names a parked authorization, and the user binding is made server-side from
+ * the token sent below, so a leaked pointer authorizes nobody.
+ */
+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.