Extension Core Infrastructure

--- name: extension-core-infrastructure description: Core infrastructure providing backend connection configuration, storage client, and React app entry point. version: 1.4.0 compatibility: npm: "@caffeineai/core-infrastructure": "^1.4.0" "@caffeineai/object-storage": "^1.1.0" caffeineai-subscription: [none] --- # Core Infrastructure Core infrastructure extension for [Caffeine AI](https://caffeine.ai?utm_source=caffeine-skill&utm_medium=referral). ## Overview This component provides the foundational infrastructure for all projects: backend connection configuration, Internet Identity authentication hooks, and actor management utilities. ## Requirements ``` "@caffeineai/core-infrastructure": "^1.4.0" "@caffeineai/object-storage": "^1.1.0" "@icp-sdk/auth": "^7.1.0" "@icp-sdk/core": "^5.3.0" ``` `@caffeineai/object-storage` is a peer dependency of core-infrastructure. Every project must install it as a direct npm dependency (the build template includes both packages). ## Integration Core infrastructure is automatically included in every project. No manual integration steps are required. # Frontend The core-infrastructure frontend package (`@caffeineai/core-infrastructure`) is automatically included in every project. ## App Entry Point Wrap the app with `InternetIdentityProvider` and `QueryClientProvider`: ```typescript import { InternetIdentityProvider } from "@caffeineai/core-infrastructure"; import { QueryClient, QueryClientProvider } from "@tanstack/react-query"; import ReactDOM from "react-dom/client"; import App from "./App"; const queryClient = new QueryClient(); ReactDOM.createRoot(document.getElementById("root")!).render( , ); ``` ## `useInternetIdentity()` — Authentication Hook Provides identity state, login, and logout for Internet Identity. ### Return Values | Field | Type | Description | |---|---|---| | `identity` | `Identity \| undefined` | The user's identity (available after login or session restore) | | `login` | `(options?: LoginOptions) => void` | Opens the II popup. Fire-and-forget — do not `await`. See [Sign-in variants](#sign-in-variants-plain-ii-google-microsoft-workspace-sso). | | `clear` | `() => void` | Logs out and clears stored identity. Fire-and-forget. | | `isAuthenticated` | `boolean` | `true` when user has a valid identity. **Use this for UI gating.** | | `isInitializing` | `boolean` | `true` while `AuthClient` is loading from IndexedDB | | `isLoggingIn` | `boolean` | `true` while the II popup is open | | `isLoginSuccess` | `boolean` | `true` only after interactive login (NOT after page reload restore) | | `isLoginError` | `boolean` | `true` if login or initialization failed | | `loginError` | `Error \| undefined` | The error object when `isLoginError` is `true` | ### Auth State Lifecycle | Scenario | `loginStatus` | `isAuthenticated` | |---|---|---| | Page load, no stored session | `"idle"` | `false` | | Restoring stored session | `"initializing"` | `false` → `true` | | Stored session restored after reload | `"idle"` | `true` | | Interactive login in progress | `"logging-in"` | `false` | | Interactive login just completed | `"success"` | `true` | | Login popup failed / cancelled | `"loginError"` | `false` | **IMPORTANT:** `isLoginSuccess` is only `true` after an interactive login via the popup — NOT when a stored identity is restored on page reload. Always use `isAuthenticated` for conditional rendering. ### Usage Gate authenticated UI on `isAuthenticated`: ```typescript const { isAuthenticated } = useInternetIdentity(); {isAuthenticated ? : } ``` Disable the login button while initializing or logging in: ```typescript const { login, isInitializing, isLoggingIn } = useInternetIdentity(); login()} disabled={isInitializing || isLoggingIn}> Sign in ``` `login()` and `clear()` are fire-and-forget — the hook's state fields (`isLoggingIn`, `isInitializing`) track the async lifecycle. Do not wrap them in local `useState` / `isPending` logic. ### Sign-in variants: plain II, Google, Microsoft, workspace SSO `login()` accepts an optional `LoginOptions` object selecting how the user signs in. All variants go through Internet Identity and produce the same identity, session behavior, and logout — they only change which screen the user sees first: ```typescript login(); // Plain Internet Identity sign-in login({ provider: "google" }); // One-click Google sign-in (II opens Google OAuth directly) login({ provider: "microsoft" }); // One-click Microsoft sign-in (II opens Microsoft OAuth directly) login({ ssoDomain: "acme.com" }); // Company/workspace SSO via the domain's identity provider ``` - **Google**: no Google API keys or OAuth client setup is needed — Internet Identity handles the OAuth flow. - **Microsoft**: no Azure/Entra app registration is needed — Internet Identity owns the OAuth client. Accepts both personal Microsoft accounts and work/school accounts. - **Workspace SSO**: the user enters their company domain (e.g. `acme.com`); Internet Identity discovers the company's OpenID Connect provider from `https:///.well-known/ii-openid-configuration` and signs in against it (works with Okta, Entra ID, and other OIDC providers the company has configured). Use this when the app needs a specific company's own tenant; use `provider: "microsoft"` for a one-click Microsoft button that needs no per-company setup. - Apple sign-in is not offered: Internet Identity returns no email or name claims for Apple, so the attribute callback would be empty. - Sessions from all variants are stored the same way: `isAuthenticated`, session restore on reload, and `clear()` behave identically regardless of the variant used. - When the backend uses `caffeineai-authorization`, Google, Microsoft, and SSO sign-ins carry verified name/email attributes (and the SSO domain) to the attribute callback automatically — see the `extension-authorization` skill. **Call `login()` only from a button's `onClick` handler.** The Internet Identity popup can only be opened while a real click event is dispatching; anything else fails with `Signer window should not be opened outside of click handler`. In particular: - Never call `login()` from a form's `onSubmit` — the `submit` event fires *after* the click event has finished, so the check fails. For the SSO domain field, use a plain `