From a72fe58e88a31efbdb05ffca5d9a4178c8e2959d Mon Sep 17 00:00:00 2001 From: b3hr4d Date: Tue, 26 May 2026 12:07:38 +0330 Subject: [PATCH 01/45] refactor: extract auth packages --- .github/workflows/release.yml | 2 + README.md | 15 +- .../content/docs/framework/react-setup.mdx | 19 +- .../content/docs/guides/authentication.mdx | 31 +- .../libs/classes/AuthenticationManager.md | 134 +++ .../content/docs/libs/classes/CallError.md | 7 +- .../docs/libs/classes/CanisterError.md | 15 +- .../docs/libs/classes/ClientManager.md | 207 +---- .../docs/libs/classes/DisplayCodecVisitor.md | 49 +- .../docs/libs/classes/DisplayReactor.md | 59 +- .../libs/classes/IdentityAttributesManager.md | 75 ++ docs/src/content/docs/libs/classes/Reactor.md | 47 +- .../docs/libs/classes/ValidationError.md | 13 +- .../docs/libs/functions/createNullVariant.md | 3 +- .../libs/functions/createPollingStrategy.md | 3 +- .../docs/libs/functions/createVariant.md | 3 +- .../decodeIdentityAttributeValues.md | 3 +- .../docs/libs/functions/didToDisplayCodec.md | 3 +- .../docs/libs/functions/didToDisplayCodecs.md | 3 +- .../docs/libs/functions/didTypeFromArray.md | 3 +- .../docs/libs/functions/extractOkResult.md | 3 +- .../docs/libs/functions/formatHexDisplay.md | 3 +- .../docs/libs/functions/fromZodSchema.md | 3 +- .../docs/libs/functions/generateKey.md | 3 +- .../libs/functions/getNetworkByHostname.md | 3 +- .../libs/functions/getProcessEnvNetwork.md | 6 +- .../docs/libs/functions/getVariantKey.md | 3 +- .../docs/libs/functions/getVariantKeyValue.md | 3 +- .../docs/libs/functions/getVariantValue.md | 3 +- .../libs/functions/getVariantValueByKey.md | 3 +- .../docs/libs/functions/hexToUint8Array.md | 3 +- .../libs/functions/identityAttributeKeys.md | 3 +- .../docs/libs/functions/isCallError.md | 3 +- .../docs/libs/functions/isCanisterError.md | 5 +- docs/src/content/docs/libs/functions/isDev.md | 6 +- .../libs/functions/isInLocalOrDevelopment.md | 5 +- .../docs/libs/functions/isKeyMatchVariant.md | 3 +- .../content/docs/libs/functions/isNullish.md | 3 +- .../docs/libs/functions/isValidationError.md | 3 +- .../docs/libs/functions/jsonToString.md | 3 +- .../localInternetIdentityProvider.md | 25 + .../content/docs/libs/functions/nonNullish.md | 3 +- .../libs/functions/normalizeOpenIdProvider.md | 3 +- .../normalizeSignedIdentityAttributes.md | 3 +- .../functions/processQueryCallResponse.md | 3 +- .../functions/processUpdateCallResponse.md | 3 +- .../functions/resolveIdentityAttributeKeys.md | 3 +- .../libs/functions/transformArgsWithCodec.md | 3 +- .../functions/transformResultWithCodec.md | 3 +- .../docs/libs/functions/uint8ArrayToHex.md | 5 +- docs/src/content/docs/libs/index.md | 36 +- .../docs/libs/interfaces/ActorDisplayCodec.md | 9 +- .../docs/libs/interfaces/ActorMethodCodecs.md | 7 +- .../docs/libs/interfaces/AgentState.md | 13 +- .../content/docs/libs/interfaces/ApiError.md | 9 +- .../docs/libs/interfaces/AuthClientLike.md | 13 +- .../interfaces/AuthClientSignInOptions.md | 9 +- .../content/docs/libs/interfaces/AuthState.md | 19 +- .../interfaces/AuthenticationClientOptions.md | 35 + .../AuthenticationManagerParameters.md | 55 ++ .../interfaces/AuthenticationSignInOptions.md | 101 +++ .../ClientManagerAuthClientOptions.md | 36 - .../interfaces/ClientManagerParameters.md | 31 +- .../interfaces/ClientManagerSignInOptions.md | 102 --- .../docs/libs/interfaces/DefaultActorType.md | 3 +- .../interfaces/DisplayReactorParameters.md | 15 +- .../interfaces/IdentityAttributeRequest.md | 7 +- .../interfaces/IdentityAttributeResult.md | 13 +- .../interfaces/IdentityAttributeValues.md | 9 +- .../docs/libs/interfaces/PollingConfig.md | 21 +- .../docs/libs/interfaces/ReactorCallParams.md | 11 +- .../docs/libs/interfaces/ReactorParameters.md | 13 +- .../libs/interfaces/ReactorQueryParams.md | 9 +- .../RequestIdentityAttributesParameters.md | 19 +- ...questOpenIdIdentityAttributesParameters.md | 19 +- .../interfaces/SignedIdentityAttributes.md | 9 +- .../libs/interfaces/TransformArgsRegistry.md | 7 +- .../interfaces/TransformReturnRegistry.md | 7 +- .../libs/interfaces/UpdateAgentParameters.md | 5 +- .../docs/libs/interfaces/ValidationIssue.md | 9 +- .../type-aliases/ActorMethodParameters.md | 3 +- .../type-aliases/ActorMethodReturnType.md | 3 +- .../docs/libs/type-aliases/ActorMethodType.md | 5 +- .../docs/libs/type-aliases/ArgsType.md | 3 +- .../docs/libs/type-aliases/AsDisplayArgs.md | 3 +- .../docs/libs/type-aliases/BaseActor.md | 3 +- .../docs/libs/type-aliases/BlobType.md | 3 +- .../docs/libs/type-aliases/CandidKeyValue.md | 3 +- .../docs/libs/type-aliases/CandidVariant.md | 3 +- .../libs/type-aliases/CandidVariantKey.md | 3 +- .../CandidVariantToIntersection.md | 3 +- .../libs/type-aliases/CandidVariantValue.md | 3 +- .../docs/libs/type-aliases/CanisterId.md | 3 +- .../docs/libs/type-aliases/DisplayCodec.md | 3 +- .../libs/type-aliases/DisplayCommonType.md | 3 +- .../docs/libs/type-aliases/DisplayOf.md | 3 +- .../libs/type-aliases/DisplayValidator.md | 3 +- .../docs/libs/type-aliases/ErrResult.md | 3 +- .../docs/libs/type-aliases/FunctionName.md | 3 +- .../docs/libs/type-aliases/FunctionType.md | 3 +- .../IdentityAttributeOpenIdProvider.md | 3 +- .../docs/libs/type-aliases/IsBlobType.md | 3 +- .../docs/libs/type-aliases/IsCandidVariant.md | 3 +- .../libs/type-aliases/IsOkErrResultType.md | 3 +- .../docs/libs/type-aliases/IsOptionalType.md | 3 +- .../docs/libs/type-aliases/NullishType.md | 3 +- .../docs/libs/type-aliases/OkResult.md | 3 +- .../docs/libs/type-aliases/ReactorArgs.md | 3 +- .../libs/type-aliases/ReactorReturnErr.md | 3 +- .../docs/libs/type-aliases/ReactorReturnOk.md | 3 +- .../docs/libs/type-aliases/TransformKey.md | 3 +- .../docs/libs/type-aliases/UnionToTuple.md | 3 +- .../libs/type-aliases/UnwrapOkErrResult.md | 3 +- .../libs/type-aliases/ValidationResult.md | 3 +- .../docs/libs/type-aliases/Validator.md | 3 +- .../libs/variables/IC_HOST_NETWORK_URI.md | 3 +- .../IC_INTERNET_IDENTITY_PROVIDER.md | 5 +- .../IDENTITY_ATTRIBUTES_BETA_PROVIDER.md | 10 +- .../variables/IDENTITY_ATTRIBUTES_PROVIDER.md | 9 + .../docs/libs/variables/LOCAL_HOSTS.md | 3 +- .../libs/variables/LOCAL_HOST_NETWORK_URI.md | 3 +- .../LOCAL_INTERNET_IDENTITY_CANISTER_ID.md | 11 + .../LOCAL_INTERNET_IDENTITY_PROVIDER.md | 7 +- .../docs/libs/variables/REMOTE_HOSTS.md | 3 +- .../content/docs/libs/variables/VERSION.md | 3 +- docs/src/content/docs/packages/core.mdx | 25 +- docs/src/content/docs/packages/react.mdx | 28 +- .../content/docs/reference/ClientManager.mdx | 69 +- .../reference/createActorHooks/overview.mdx | 14 +- .../reference/createAuthHooks/overview.mdx | 24 +- docs/tsconfig.typedoc.json | 17 + docs/typedoc-entry.ts | 2 + docs/typedoc.json | 7 +- e2e/package.json | 2 + e2e/src/test/agent.test.tsx | 9 +- e2e/src/test/react.test.tsx | 7 +- examples/all-in-one-demo/package.json | 2 + examples/all-in-one-demo/src/App.tsx | 3 +- examples/all-in-one-demo/src/lib/authHooks.ts | 6 +- examples/ckbtc-wallet/package.json | 2 + examples/ckbtc-wallet/src/reactor.ts | 6 +- examples/custom-provider/package.json | 2 + examples/custom-provider/src/reactor.ts | 6 +- .../icp-reactor-demo/frontend/package.json | 2 + .../icp-reactor-demo/frontend/src/App.tsx | 3 +- .../frontend/src/lib/client.ts | 10 +- examples/identity-attributes-demo/README.md | 2 +- .../identity-attributes-demo/package.json | 2 + examples/identity-attributes-demo/src/App.tsx | 2 +- .../identity-attributes-demo/src/reactor.ts | 17 +- examples/multiple-canister/package.json | 2 + examples/multiple-canister/src/reactor.ts | 6 +- examples/nextjs/package.json | 2 + examples/nextjs/src/service/client.ts | 7 +- examples/query-demo/package.json | 2 + examples/query-demo/src/reactor.ts | 6 +- .../suspense-infinite-query-demo/package.json | 2 + .../suspense-infinite-query-demo/src/store.ts | 10 +- examples/tanstack-router/package.json | 2 + examples/tanstack-router/src/lib/client.ts | 6 +- examples/typescript-demo/package.json | 1 + examples/typescript-demo/src/main.ts | 10 +- packages/auth-react/README.md | 16 + packages/auth-react/package.json | 84 ++ .../src/createAuthHooks.ts | 110 +-- .../src/createIdentityAttributeHooks.ts | 83 ++ packages/auth-react/src/index.ts | 2 + .../tests/createAuthHooks.test.tsx | 102 ++- packages/auth-react/tsconfig.json | 16 + packages/auth-react/tsconfig.test.json | 8 + packages/auth-react/vitest.config.ts | 10 + packages/auth/README.md | 21 + packages/auth/package.json | 71 ++ packages/auth/src/authentication-manager.ts | 467 +++++++++++ packages/auth/src/constants.ts | 20 + .../auth/src/identity-attributes-manager.ts | 124 +++ .../{core => auth}/src/identity-attributes.ts | 4 +- packages/auth/src/index.ts | 5 + packages/auth/src/types.ts | 89 ++ .../auth/tests/authentication-manager.test.ts | 218 +++++ .../tests/identity-attributes-manager.test.ts | 135 +++ .../tests/identity-attributes.test.ts | 2 +- packages/auth/tsconfig.json | 19 + packages/auth/vitest.config.ts | 7 + packages/core/README.md | 59 +- packages/core/package.json | 5 - packages/core/src/client.ts | 583 +------------ packages/core/src/index.ts | 1 - packages/core/src/types/client.ts | 113 +-- packages/core/src/utils/constants.ts | 31 - packages/core/tests/client-manager.test.ts | 780 ++---------------- packages/react/README.md | 28 +- packages/react/package.json | 9 +- packages/react/src/index.ts | 1 - packages/react/tests/hooks.test.tsx | 15 +- pnpm-lock.yaml | 92 ++- scripts/release.js | 6 +- scripts/sync-example-versions.js | 8 +- 198 files changed, 2726 insertions(+), 2576 deletions(-) create mode 100644 docs/src/content/docs/libs/classes/AuthenticationManager.md create mode 100644 docs/src/content/docs/libs/classes/IdentityAttributesManager.md create mode 100644 docs/src/content/docs/libs/functions/localInternetIdentityProvider.md create mode 100644 docs/src/content/docs/libs/interfaces/AuthenticationClientOptions.md create mode 100644 docs/src/content/docs/libs/interfaces/AuthenticationManagerParameters.md create mode 100644 docs/src/content/docs/libs/interfaces/AuthenticationSignInOptions.md delete mode 100644 docs/src/content/docs/libs/interfaces/ClientManagerAuthClientOptions.md delete mode 100644 docs/src/content/docs/libs/interfaces/ClientManagerSignInOptions.md create mode 100644 docs/src/content/docs/libs/variables/IDENTITY_ATTRIBUTES_PROVIDER.md create mode 100644 docs/src/content/docs/libs/variables/LOCAL_INTERNET_IDENTITY_CANISTER_ID.md create mode 100644 docs/tsconfig.typedoc.json create mode 100644 docs/typedoc-entry.ts create mode 100644 packages/auth-react/README.md create mode 100644 packages/auth-react/package.json rename packages/{react => auth-react}/src/createAuthHooks.ts (55%) create mode 100644 packages/auth-react/src/createIdentityAttributeHooks.ts create mode 100644 packages/auth-react/src/index.ts rename packages/{react => auth-react}/tests/createAuthHooks.test.tsx (78%) create mode 100644 packages/auth-react/tsconfig.json create mode 100644 packages/auth-react/tsconfig.test.json create mode 100644 packages/auth-react/vitest.config.ts create mode 100644 packages/auth/README.md create mode 100644 packages/auth/package.json create mode 100644 packages/auth/src/authentication-manager.ts create mode 100644 packages/auth/src/constants.ts create mode 100644 packages/auth/src/identity-attributes-manager.ts rename packages/{core => auth}/src/identity-attributes.ts (98%) create mode 100644 packages/auth/src/index.ts create mode 100644 packages/auth/src/types.ts create mode 100644 packages/auth/tests/authentication-manager.test.ts create mode 100644 packages/auth/tests/identity-attributes-manager.test.ts rename packages/{core => auth}/tests/identity-attributes.test.ts (97%) create mode 100644 packages/auth/tsconfig.json create mode 100644 packages/auth/vitest.config.ts diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index bbc5843067..220a6b1990 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -20,6 +20,8 @@ jobs: workspace: - packages/core - packages/react + - packages/auth + - packages/auth-react - packages/candid steps: - name: Checkout diff --git a/README.md b/README.md index 686dce31da..196d0bdeb6 100644 --- a/README.md +++ b/README.md @@ -38,6 +38,8 @@ IC Reactor gives you a higher-level API than raw `Actor` usage while keeping typ | --------------------------------------------------- | ------------------------------------------------------------------------------ | | [`@ic-reactor/core`](./packages/core) | Core runtime (`ClientManager`, `Reactor`, `DisplayReactor`, cache integration) | | [`@ic-reactor/react`](./packages/react) | React hooks + query/mutation factories | +| [`@ic-reactor/auth`](./packages/auth) | Internet Identity authentication and identity attributes | +| [`@ic-reactor/auth-react`](./packages/auth-react) | React hooks for the auth package | | [`@ic-reactor/candid`](./packages/candid) | Dynamic Candid parsing and runtime reactors | | [`@ic-reactor/parser`](./packages/parser) | Local Candid parser (WASM-based) | | [`@ic-reactor/codegen`](./packages/codegen) | Shared codegen pipeline used by CLI and Vite plugin | @@ -61,8 +63,8 @@ pnpm add @ic-reactor/core @icp-sdk/core @tanstack/query-core ### Optional packages ```bash -# Internet Identity auth helpers -pnpm add @icp-sdk/auth +# Internet Identity auth helpers for React +pnpm add @ic-reactor/auth @ic-reactor/auth-react @icp-sdk/auth # Dynamic Candid support (explorers/dev tools) pnpm add @ic-reactor/candid @ic-reactor/parser @@ -75,6 +77,7 @@ pnpm add @ic-reactor/candid @ic-reactor/parser ```ts // src/reactor.ts import { ClientManager, Reactor } from "@ic-reactor/react" +import { AuthenticationManager } from "@ic-reactor/auth" import { QueryClient } from "@tanstack/react-query" import { idlFactory, type _SERVICE } from "./declarations/my_canister" @@ -84,6 +87,7 @@ export const clientManager = new ClientManager({ queryClient, // withCanisterEnv: true, // optional: useful in local/dev setups }) +export const authentication = new AuthenticationManager({ clientManager }) export const backendReactor = new Reactor<_SERVICE>({ clientManager, @@ -97,8 +101,9 @@ export const backendReactor = new Reactor<_SERVICE>({ ```ts // src/hooks.ts -import { createActorHooks, createAuthHooks } from "@ic-reactor/react" -import { backendReactor, clientManager } from "./reactor" +import { createActorHooks } from "@ic-reactor/react" +import { createAuthHooks } from "@ic-reactor/auth-react" +import { backendReactor, authentication } from "./reactor" export const { useActorQuery, @@ -107,7 +112,7 @@ export const { useActorInfiniteQuery, } = createActorHooks(backendReactor) -export const { useAuth, useUserPrincipal } = createAuthHooks(clientManager) +export const { useAuth, useUserPrincipal } = createAuthHooks(authentication) ``` ### 3. Use in React components diff --git a/docs/src/content/docs/framework/react-setup.mdx b/docs/src/content/docs/framework/react-setup.mdx index 420c26813a..09e9dc9395 100644 --- a/docs/src/content/docs/framework/react-setup.mdx +++ b/docs/src/content/docs/framework/react-setup.mdx @@ -54,7 +54,9 @@ This guide covers the complete setup of IC Reactor in a React application, inclu ```typescript // src/reactor/hooks.ts - import { createActorHooks, createAuthHooks } from "@ic-reactor/react" + import { createActorHooks } from "@ic-reactor/react" + import { AuthenticationManager } from "@ic-reactor/auth" + import { createAuthHooks } from "@ic-reactor/auth-react" import { backend, clientManager } from "./index" // Actor hooks for your canister @@ -66,11 +68,9 @@ This guide covers the complete setup of IC Reactor in a React application, inclu } = createActorHooks(backend) // Auth hooks for authentication - export const { - useAuth, - useUserPrincipal, - useAgentState, - } = createAuthHooks(clientManager) + export const authentication = new AuthenticationManager({ clientManager }) + export const { useAuth, useUserPrincipal, useAgentState } = + createAuthHooks(authentication) ``` 3. ### Setup Provider (Optional) @@ -282,12 +282,15 @@ export const backend = new Reactor({ ```typescript // src/reactor/hooks.ts -import { createActorHooks, createAuthHooks } from "@ic-reactor/react" +import { createActorHooks } from "@ic-reactor/react" +import { AuthenticationManager } from "@ic-reactor/auth" +import { createAuthHooks } from "@ic-reactor/auth-react" import { ledger, backend, clientManager } from "./index" export const ledgerHooks = createActorHooks(ledger) export const backendHooks = createActorHooks(backend) -export const authHooks = createAuthHooks(clientManager) +export const authentication = new AuthenticationManager({ clientManager }) +export const authHooks = createAuthHooks(authentication) // Export individual hooks for convenience export const { diff --git a/docs/src/content/docs/guides/authentication.mdx b/docs/src/content/docs/guides/authentication.mdx index 01a19359f7..4112b88011 100644 --- a/docs/src/content/docs/guides/authentication.mdx +++ b/docs/src/content/docs/guides/authentication.mdx @@ -10,25 +10,24 @@ IC Reactor provides seamless integration with Internet Identity for authenticati ## Setup -Authentication hooks are created by passing your `ClientManager` instance to `createAuthHooks`: +Authentication hooks are created from an `AuthenticationManager`, which wraps +the shared `ClientManager` without adding authentication APIs to it: ```typescript // src/reactor/hooks.ts -import { createAuthHooks } from "@ic-reactor/react" +import { AuthenticationManager } from "@ic-reactor/auth" +import { createAuthHooks } from "@ic-reactor/auth-react" import { clientManager } from "./index" -export const { - useAuth, - useUserPrincipal, - useAgentState, - useIdentityAttributes, -} = createAuthHooks(clientManager) +export const authentication = new AuthenticationManager({ clientManager }) +export const { useAuth, useUserPrincipal, useAgentState } = + createAuthHooks(authentication) ``` ## useAuth @@ -101,6 +100,14 @@ component needs to request attributes and send the signed payload to a backend o canister for verification. ```tsx +import { IdentityAttributesManager } from "@ic-reactor/auth" +import { createIdentityAttributeHooks } from "@ic-reactor/auth-react" +import { authentication } from "../reactor/hooks" + +const identityAttributes = new IdentityAttributesManager(authentication) +export const { useIdentityAttributes } = + createIdentityAttributeHooks(identityAttributes) + import { useIdentityAttributes } from "../reactor/hooks" function RegisterWithOpenIdProvider() { @@ -139,7 +146,7 @@ function RegisterWithOpenIdProvider() { Pass a documented auth provider alias (`"google"`, `"apple"`, or `"microsoft"`) or an issuer URL such as `"https://issuer.example.com"` for custom OpenID providers. For non-React code, use -`clientManager.requestOpenIdIdentityAttributes()` directly. +`identityAttributes.requestOpenId()` directly.