@ic-reactor/react 3.6.0 → 3.7.0

package/src/auth/identity-attributes-manager.ts

@@ -0,0 +1,127 @@
+import type {
+  AuthenticationClientOptions,
+  IdentityAttributeResult,
+  RequestIdentityAttributesParameters,
+  RequestOpenIdIdentityAttributesParameters,
+} from "./types"
+
+import { AuthenticationManager } from "./authentication-manager"
+import {
+  decodeIdentityAttributeValues,
+  identityAttributeKeys,
+  normalizeSignedIdentityAttributes,
+} from "./identity-attributes"
+
+/**
+ * Requests and decodes signed identity attributes for an authenticated
+ * Internet Identity session.
+ *
+ * @example
+ * ```ts
+ * const attributes = new IdentityAttributesManager(authentication)
+ * const result = await attributes.request({ keys: ["name"] })
+ * ```
+ */
+export class IdentityAttributesManager {
+  constructor(public readonly authentication: AuthenticationManager) {}
+
+  public request = async ({
+    keys,
+    nonce,
+    identityProvider,
+    openIdProvider,
+    windowOpenerFeatures,
+    signIn = true,
+    maxTimeToLive,
+    targets,
+  }: RequestIdentityAttributesParameters): Promise<IdentityAttributeResult> => {
+    const authClient = await this.authentication.ensureClient(
+      getAuthClientOptions({
+        identityProvider,
+        windowOpenerFeatures,
+        openIdProvider,
+      })
+    )
+
+    if (!authClient) {
+      throw new Error(
+        "Authentication module is missing or failed to initialize. To request identity attributes, please install @icp-sdk/auth v7 or provide a compatible authClient."
+      )
+    }
+
+    this.authentication.setAuthenticating()
+
+    try {
+      const identityPromise = signIn
+        ? this.authentication.signInOrRecoverIdentity({
+            maxTimeToLive,
+            targets,
+          })
+        : Promise.resolve(authClient.getIdentity())
+      const requestPromise = authClient.requestAttributes({ keys, nonce })
+
+      const [signedAttributes, identity] = await Promise.all([
+        requestPromise,
+        identityPromise,
+      ])
+
+      const finalIdentity = identity ?? (await authClient.getIdentity())
+      const isAuthenticated = await authClient.isAuthenticated()
+      await this.authentication.commitIdentity(finalIdentity, isAuthenticated)
+
+      const normalizedSignedAttributes =
+        normalizeSignedIdentityAttributes(signedAttributes)
+
+      return {
+        principal: finalIdentity.getPrincipal().toText(),
+        requestedKeys: keys,
+        signedAttributes: normalizedSignedAttributes,
+        decodedAttributes: decodeIdentityAttributeValues(
+          normalizedSignedAttributes.data,
+          keys
+        ),
+        completedAt: new Date().toISOString(),
+      }
+    } catch (error) {
+      this.authentication.setAuthenticationError(error as Error)
+      throw error
+    }
+  }
+
+  public requestOpenId = async ({
+    nonce,
+    openIdProvider,
+    keys,
+    identityProvider,
+    windowOpenerFeatures,
+    signIn,
+    maxTimeToLive,
+    targets,
+  }: RequestOpenIdIdentityAttributesParameters): Promise<IdentityAttributeResult> => {
+    return this.request({
+      keys: identityAttributeKeys({ openIdProvider, keys }),
+      nonce,
+      identityProvider,
+      openIdProvider,
+      windowOpenerFeatures,
+      signIn,
+      maxTimeToLive,
+      targets,
+    })
+  }
+}
+
+function getAuthClientOptions(
+  options: AuthenticationClientOptions
+): AuthenticationClientOptions {
+  return {
+    identityProvider: options.identityProvider,
+    windowOpenerFeatures: options.windowOpenerFeatures,
+    openIdProvider:
+      options.openIdProvider === "google" ||
+      options.openIdProvider === "apple" ||
+      options.openIdProvider === "microsoft"
+        ? options.openIdProvider
+        : undefined,
+  }
+}

package/src/auth/identity-attributes.ts

@@ -0,0 +1,270 @@
+import { IDL } from "@icp-sdk/core/candid"
+
+import type {
+  IdentityAttributeOpenIdProvider,
+  IdentityAttributeValues,
+  SignedIdentityAttributes,
+} from "./types"
+import { IC_INTERNET_IDENTITY_PROVIDER } from "./constants"
+
+export const IDENTITY_ATTRIBUTES_PROVIDER = IC_INTERNET_IDENTITY_PROVIDER
+
+/**
+ * @deprecated Use the default ClientManager identity provider or
+ * `IDENTITY_ATTRIBUTES_PROVIDER` instead.
+ */
+export const IDENTITY_ATTRIBUTES_BETA_PROVIDER = IDENTITY_ATTRIBUTES_PROVIDER
+
+const OPEN_ID_PROVIDER_URLS = {
+  apple: "https://appleid.apple.com",
+  google: "https://accounts.google.com",
+  microsoft: "https://login.microsoftonline.com/{tid}/v2.0",
+} as const
+
+export function identityAttributeKeys({
+  openIdProvider,
+  keys,
+}: {
+  openIdProvider: IdentityAttributeOpenIdProvider
+  keys: string[]
+}): string[] {
+  const provider = normalizeOpenIdProvider(openIdProvider)
+  return keys.map((key) => `openid:${provider}:${key}`)
+}
+
+export function normalizeOpenIdProvider(
+  openIdProvider: IdentityAttributeOpenIdProvider
+): string {
+  return (
+    OPEN_ID_PROVIDER_URLS[
+      openIdProvider as keyof typeof OPEN_ID_PROVIDER_URLS
+    ] ?? openIdProvider
+  )
+}
+
+export async function resolveIdentityAttributeKeys({
+  openIdProvider,
+  keys,
+}: {
+  openIdProvider: IdentityAttributeOpenIdProvider
+  keys: string[]
+}): Promise<string[]> {
+  return identityAttributeKeys({ openIdProvider, keys })
+}
+
+export function decodeIdentityAttributeValues(
+  data: Uint8Array,
+  requestedKeys: string[]
+): IdentityAttributeValues {
+  const requestedKeyMap = requestedKeys.reduce<Record<string, string>>(
+    (acc, key) => {
+      acc[key] = identityAttributeDisplayKey(key)
+      acc[identityAttributeDisplayKey(key)] = identityAttributeDisplayKey(key)
+      return acc
+    },
+    {}
+  )
+
+  const decodedValues = decodeCandidAttributeValues(data, requestedKeyMap)
+  if (Object.keys(decodedValues).length > 0) {
+    return decodedValues
+  }
+
+  return extractPrintableAttributeValues(data, requestedKeys)
+}
+
+function decodeCandidAttributeValues(
+  data: Uint8Array,
+  requestedKeyMap: Record<string, string>
+): IdentityAttributeValues {
+  const textPairs = IDL.Vec(IDL.Tuple(IDL.Text, IDL.Text))
+  const recordPairs = IDL.Vec(
+    IDL.Record({
+      key: IDL.Text,
+      value: IDL.Text,
+    })
+  )
+
+  const candidates = [
+    [textPairs],
+    [recordPairs],
+    [IDL.Record({ attributes: textPairs })],
+    [IDL.Record({ values: textPairs })],
+    [IDL.Record({ attributes: recordPairs })],
+    [IDL.Record({ values: recordPairs })],
+  ]
+
+  for (const candidate of candidates) {
+    try {
+      const decoded = IDL.decode(candidate, data)
+      const values = collectDecodedAttributeValues(decoded, requestedKeyMap)
+      if (Object.keys(values).length > 0) {
+        return values
+      }
+    } catch {
+      // Try the next known beta payload shape, then fall back to text extraction.
+    }
+  }
+
+  return {}
+}
+
+function collectDecodedAttributeValues(
+  value: unknown,
+  requestedKeyMap: Record<string, string>,
+  activeKey?: string
+): IdentityAttributeValues {
+  const values: IdentityAttributeValues = {}
+
+  if (typeof value === "string") {
+    const displayKey = requestedKeyMap[value]
+    if (displayKey) {
+      return values
+    }
+    if (activeKey && isPrintableTextValue(value)) {
+      values[activeKey] = value
+    }
+    return values
+  }
+
+  if (Array.isArray(value)) {
+    if (value.length === 2 && typeof value[0] === "string") {
+      const displayKey = requestedKeyMap[value[0]]
+      if (
+        displayKey &&
+        typeof value[1] === "string" &&
+        isPrintableTextValue(value[1])
+      ) {
+        values[displayKey] = value[1]
+        return values
+      }
+    }
+
+    for (const item of value) {
+      Object.assign(
+        values,
+        collectDecodedAttributeValues(item, requestedKeyMap, activeKey)
+      )
+    }
+    return values
+  }
+
+  if (value && typeof value === "object") {
+    const record = value as Record<string, unknown>
+    if (typeof record.key === "string" && typeof record.value === "string") {
+      const displayKey = requestedKeyMap[record.key]
+      if (displayKey && isPrintableTextValue(record.value)) {
+        values[displayKey] = record.value
+        return values
+      }
+    }
+
+    for (const [key, nested] of Object.entries(record)) {
+      const displayKey = requestedKeyMap[key] ?? activeKey
+      if (
+        displayKey &&
+        typeof nested === "string" &&
+        isPrintableTextValue(nested)
+      ) {
+        values[displayKey] = nested
+        continue
+      }
+      Object.assign(
+        values,
+        collectDecodedAttributeValues(nested, requestedKeyMap, displayKey)
+      )
+    }
+  }
+
+  return values
+}
+
+function extractPrintableAttributeValues(
+  data: Uint8Array,
+  requestedKeys: string[]
+): IdentityAttributeValues {
+  const text = new TextDecoder().decode(data)
+  const values: IdentityAttributeValues = {}
+
+  for (const requestedKey of requestedKeys) {
+    const start = text.indexOf(requestedKey)
+    if (start === -1) {
+      continue
+    }
+
+    const tail = text.slice(start + requestedKey.length)
+    const printableRuns = tail.match(/[\x20-\x7E]{2,512}/g) ?? []
+    const value = printableRuns
+      .map((candidate) =>
+        cleanPrintableAttributeValue(candidate, requestedKeys)
+      )
+      .find(
+        (candidate) =>
+          isPrintableTextValue(candidate) &&
+          candidate !== requestedKey &&
+          !candidate.startsWith("openid:")
+      )
+
+    if (value) {
+      values[identityAttributeDisplayKey(requestedKey)] = value.trim()
+    }
+  }
+
+  return values
+}
+
+function cleanPrintableAttributeValue(
+  value: string,
+  requestedKeys: string[]
+): string {
+  let cleaned = value
+
+  for (const requestedKey of requestedKeys) {
+    const nextKeyIndex = cleaned.indexOf(requestedKey)
+    if (nextKeyIndex > 0) {
+      cleaned = cleaned.slice(
+        0,
+        trimCandidTextLengthPrefix(cleaned, nextKeyIndex)
+      )
+    }
+  }
+
+  const nextOpenIdKeyIndex = cleaned.indexOf("openid:")
+  if (nextOpenIdKeyIndex > 0) {
+    cleaned = cleaned.slice(
+      0,
+      trimCandidTextLengthPrefix(cleaned, nextOpenIdKeyIndex)
+    )
+  }
+
+  return cleaned.trim()
+}
+
+function trimCandidTextLengthPrefix(value: string, index: number): number {
+  let trimmedIndex = index
+  while (trimmedIndex > 0 && isAsciiDigit(value.charCodeAt(trimmedIndex - 1))) {
+    trimmedIndex -= 1
+  }
+  return trimmedIndex
+}
+
+function isAsciiDigit(charCode: number): boolean {
+  return charCode >= 48 && charCode <= 57
+}
+
+function identityAttributeDisplayKey(key: string): string {
+  return key.split(":").pop() || key
+}
+
+function isPrintableTextValue(value: string): boolean {
+  return value.length > 0 && value.length <= 512 && /^[\x20-\x7E]+$/.test(value)
+}
+
+export function normalizeSignedIdentityAttributes(
+  attributes: SignedIdentityAttributes
+): SignedIdentityAttributes {
+  return {
+    data: new Uint8Array(attributes.data),
+    signature: new Uint8Array(attributes.signature),
+  }
+}

package/src/auth/index.ts

@@ -0,0 +1,7 @@
+export * from "./authentication-manager"
+export * from "./identity-attributes-manager"
+export * from "./identity-attributes"
+export * from "./constants"
+export * from "./types"
+export * from "../hooks/createAuthHooks"
+export * from "./createIdentityAttributeHooks"

package/src/auth/types.ts

@@ -0,0 +1,88 @@
+import type { Identity } from "@icp-sdk/core/agent"
+import type { Principal } from "@icp-sdk/core/principal"
+
+export interface SignedIdentityAttributes {
+  data: Uint8Array
+  signature: Uint8Array
+}
+
+export interface IdentityAttributeRequest {
+  keys: string[]
+  nonce: Uint8Array
+}
+
+export interface IdentityAttributeValues {
+  email?: string
+  name?: string
+  verified_email?: string
+  [key: string]: string | undefined
+}
+
+export interface IdentityAttributeResult {
+  principal: string
+  requestedKeys: string[]
+  signedAttributes: SignedIdentityAttributes
+  decodedAttributes: IdentityAttributeValues
+  completedAt: string
+}
+
+type IdentityAttributeOpenIdProviderAlias = "google" | "apple" | "microsoft"
+
+export type IdentityAttributeOpenIdProvider =
+  IdentityAttributeOpenIdProviderAlias | (string & {})
+
+export interface AuthenticationClientOptions {
+  identityProvider?: string | URL
+  windowOpenerFeatures?: string
+  openIdProvider?: IdentityAttributeOpenIdProvider
+}
+
+export interface AuthClientSignInOptions {
+  maxTimeToLive?: bigint
+  targets?: Principal[]
+}
+
+export interface AuthenticationSignInOptions
+  extends AuthClientSignInOptions, AuthenticationClientOptions {
+  onSuccess?: () => void | Promise<void>
+  onError?: (error?: string) => void | Promise<void>
+}
+
+export interface RequestIdentityAttributesParameters {
+  keys: string[]
+  nonce: Uint8Array
+  identityProvider?: string | URL
+  openIdProvider?: IdentityAttributeOpenIdProvider
+  windowOpenerFeatures?: string
+  signIn?: boolean
+  maxTimeToLive?: bigint
+  targets?: Principal[]
+}
+
+export interface RequestOpenIdIdentityAttributesParameters {
+  nonce: Uint8Array
+  openIdProvider: IdentityAttributeOpenIdProvider
+  keys: string[]
+  identityProvider?: string | URL
+  windowOpenerFeatures?: string
+  signIn?: boolean
+  maxTimeToLive?: bigint
+  targets?: Principal[]
+}
+
+export interface AuthClientLike {
+  getIdentity(): Promise<Identity> | Identity
+  isAuthenticated(): Promise<boolean> | boolean
+  signIn(options?: AuthClientSignInOptions): Promise<Identity>
+  signOut(options?: { returnTo?: string }): Promise<void>
+  requestAttributes(
+    params: IdentityAttributeRequest
+  ): Promise<SignedIdentityAttributes>
+}
+
+export interface AuthState {
+  identity: Identity | null
+  isAuthenticating: boolean
+  isAuthenticated: boolean
+  error: Error | undefined
+}

package/src/createActorHooks.ts

@@ -21,6 +21,7 @@ import {
   DisplayReactor,
   ReactorReturnErr,
   ReactorReturnOk,
+  ReactorQueryData,
   BaseActor,
   FunctionName,
   TransformKey,
@@ -46,102 +47,133 @@ import { InfiniteQueryConfig } from "./createInfiniteQuery"
 import { SuspenseInfiniteQueryConfig } from "./createSuspenseInfiniteQuery"
 import { QueryConfig, SuspenseQueryConfig, MutationConfig } from "./types"
 
-export type ActorHooks<A, T extends TransformKey> = {
+export type ActorHooks<Service, Transform extends TransformKey> = {
   useActorQuery: {
-    <M extends FunctionName<A>>(
-      config: QueryConfig<A, M, T, ReactorReturnOk<A, M, T>>
-    ): UseQueryResult<ReactorReturnOk<A, M, T>, ReactorReturnErr<A, M, T>>
-    <M extends FunctionName<A>, TData>(
-      config: QueryConfig<A, M, T, TData>
-    ): UseQueryResult<TData, ReactorReturnErr<A, M, T>>
+    <Method extends FunctionName<Service>>(
+      config: QueryConfig<
+        Service,
+        Method,
+        Transform,
+        ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>
+      >
+    ): UseQueryResult<
+      ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>,
+      ReactorReturnErr<Service, Method, Transform>
+    >
+    <Method extends FunctionName<Service>, TData>(
+      config: QueryConfig<Service, Method, Transform, TData>
+    ): UseQueryResult<TData, ReactorReturnErr<Service, Method, Transform>>
   }
 
   useActorSuspenseQuery: {
-    <M extends FunctionName<A>>(
-      config: SuspenseQueryConfig<A, M, T, ReactorReturnOk<A, M, T>>
+    <Method extends FunctionName<Service>>(
+      config: SuspenseQueryConfig<
+        Service,
+        Method,
+        Transform,
+        ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>
+      >
+    ): UseSuspenseQueryResult<
+      ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>,
+      ReactorReturnErr<Service, Method, Transform>
+    >
+    <Method extends FunctionName<Service>, TData>(
+      config: SuspenseQueryConfig<Service, Method, Transform, TData>
     ): UseSuspenseQueryResult<
-      ReactorReturnOk<A, M, T>,
-      ReactorReturnErr<A, M, T>
+      TData,
+      ReactorReturnErr<Service, Method, Transform>
     >
-    <M extends FunctionName<A>, TData>(
-      config: SuspenseQueryConfig<A, M, T, TData>
-    ): UseSuspenseQueryResult<TData, ReactorReturnErr<A, M, T>>
   }
 
-  useActorInfiniteQuery: <M extends FunctionName<A>, TPageParam = unknown>(
-    config: InfiniteQueryConfig<A, M, T, TPageParam>
+  useActorInfiniteQuery: <
+    Method extends FunctionName<Service>,
+    TPageParam = unknown,
+  >(
+    config: InfiniteQueryConfig<Service, Method, Transform, TPageParam>
   ) => UseInfiniteQueryResult<
-    InfiniteData<ReactorReturnOk<A, M, T>, TPageParam>,
-    ReactorReturnErr<A, M, T>
+    InfiniteData<
+      ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>,
+      TPageParam
+    >,
+    ReactorReturnErr<Service, Method, Transform>
   >
 
   useActorSuspenseInfiniteQuery: <
-    M extends FunctionName<A>,
+    Method extends FunctionName<Service>,
     TPageParam = unknown,
   >(
-    config: SuspenseInfiniteQueryConfig<A, M, T, TPageParam>
+    config: SuspenseInfiniteQueryConfig<Service, Method, Transform, TPageParam>
   ) => UseSuspenseInfiniteQueryResult<
-    InfiniteData<ReactorReturnOk<A, M, T>, TPageParam>,
-    ReactorReturnErr<A, M, T>
+    InfiniteData<
+      ReactorQueryData<ReactorReturnOk<Service, Method, Transform>>,
+      TPageParam
+    >,
+    ReactorReturnErr<Service, Method, Transform>
   >
 
-  useActorMutation: <M extends FunctionName<A>>(
-    config: MutationConfig<A, M, T>
-  ) => UseMutationResult<ReactorReturnOk<A, M, T>, ReactorReturnErr<A, M, T>>
+  useActorMutation: <Method extends FunctionName<Service>>(
+    config: MutationConfig<Service, Method, Transform>
+  ) => UseMutationResult<
+    ReactorReturnOk<Service, Method, Transform>,
+    ReactorReturnErr<Service, Method, Transform>
+  >
 
-  useActorMethod: <M extends FunctionName<A>>(
-    config: Omit<UseActorMethodParameters<A, M, T>, "reactor">
-  ) => ReturnType<typeof useActorMethod<A, M, T>>
+  useActorMethod: <Method extends FunctionName<Service>>(
+    config: Omit<
+      UseActorMethodParameters<Service, Method, Transform>,
+      "reactor"
+    >
+  ) => ReturnType<typeof useActorMethod<Service, Method, Transform>>
 }
 
-export function createActorHooks<A>(
-  reactor: DisplayReactor<A>
-): ActorHooks<A, "display">
+export function createActorHooks<Service>(
+  reactor: DisplayReactor<Service>
+): ActorHooks<Service, "display">
 
 export function createActorHooks<
-  A = BaseActor,
-  T extends TransformKey = "candid",
->(reactor: Reactor<A, T>): ActorHooks<A, T>
+  Service = BaseActor,
+  Transform extends TransformKey = "candid",
+>(reactor: Reactor<Service, Transform>): ActorHooks<Service, Transform>
 
-export function createActorHooks<A, T extends TransformKey>(
-  reactor: Reactor<A, T>
-): ActorHooks<A, T> {
+export function createActorHooks<Service, Transform extends TransformKey>(
+  reactor: Reactor<Service, Transform>
+): ActorHooks<Service, Transform> {
   return {
     useActorQuery: ((config: any) =>
       useActorQuery({ ...config, reactor })) as ActorHooks<
-      A,
-      T
+      Service,
+      Transform
     >["useActorQuery"],
 
     useActorSuspenseQuery: ((config: any) =>
       useActorSuspenseQuery({ ...config, reactor })) as ActorHooks<
-      A,
-      T
+      Service,
+      Transform
     >["useActorSuspenseQuery"],
 
     useActorInfiniteQuery: ((config: any) =>
       useActorInfiniteQuery({ ...config, reactor })) as ActorHooks<
-      A,
-      T
+      Service,
+      Transform
     >["useActorInfiniteQuery"],
 
     useActorSuspenseInfiniteQuery: ((config: any) =>
       useActorSuspenseInfiniteQuery({ ...config, reactor })) as ActorHooks<
-      A,
-      T
+      Service,
+      Transform
     >["useActorSuspenseInfiniteQuery"],
 
     useActorMutation: ((config: any) =>
       useActorMutation({ ...config, reactor })) as ActorHooks<
-      A,
-      T
+      Service,
+      Transform
     >["useActorMutation"],
 
     useActorMethod: (config) =>
       useActorMethod({ ...config, reactor } as UseActorMethodParameters<
-        A,
+        Service,
         any,
-        T
+        Transform
       >),
   }
 }