@ic-reactor/react 3.6.0 → 3.8.0

package/src/auth/constants.ts

@@ -0,0 +1,25 @@
+export const IC_INTERNET_IDENTITY_PROVIDER = "https://id.ai/authorize"
+
+/**
+ * `ic_env` key used to provide a fully resolved Internet Identity URL.
+ */
+export const INTERNET_IDENTITY_PROVIDER_ENV_KEY = "INTERNET_IDENTITY_PROVIDER"
+
+/**
+ * Well-known Internet Identity canister ID used when deploying II locally.
+ */
+export const LOCAL_INTERNET_IDENTITY_CANISTER_ID = "rdmx6-jaaaa-aaaaa-aaadq-cai"
+
+/**
+ * Builds the local Internet Identity provider URL for the given replica port.
+ */
+export const localInternetIdentityProvider = (
+  port: number,
+  canisterId: string = LOCAL_INTERNET_IDENTITY_CANISTER_ID
+) => `http://${canisterId}.localhost:${port}/authorize`
+
+/**
+ * Legacy default URL for local Internet Identity, using port `4943`.
+ */
+export const LOCAL_INTERNET_IDENTITY_PROVIDER =
+  localInternetIdentityProvider(4943)

package/src/auth/createIdentityAttributeHooks.ts

@@ -0,0 +1,83 @@
+import { useCallback, useState } from "react"
+import type { IdentityAttributesManager } from "./identity-attributes-manager.js"
+import type {
+  IdentityAttributeResult,
+  RequestIdentityAttributesParameters,
+  RequestOpenIdIdentityAttributesParameters,
+} from "./types.js"
+
+export interface UseIdentityAttributesReturn {
+  requestAttributes: (
+    params: RequestIdentityAttributesParameters
+  ) => Promise<IdentityAttributeResult>
+  requestOpenIdAttributes: (
+    params: RequestOpenIdIdentityAttributesParameters
+  ) => Promise<IdentityAttributeResult>
+  attributes: IdentityAttributeResult | null
+  isRequestingAttributes: boolean
+  attributeError: Error | null
+  clearAttributes: () => void
+}
+
+export function createIdentityAttributeHooks(
+  identityAttributes: IdentityAttributesManager
+) {
+  const useIdentityAttributes = (): UseIdentityAttributesReturn => {
+    const [attributes, setAttributes] =
+      useState<IdentityAttributeResult | null>(null)
+    const [isRequestingAttributes, setIsRequestingAttributes] = useState(false)
+    const [attributeError, setAttributeError] = useState<Error | null>(null)
+
+    const requestAttributes = useCallback(
+      async (params: RequestIdentityAttributesParameters) => {
+        setIsRequestingAttributes(true)
+        setAttributeError(null)
+        try {
+          const result = await identityAttributes.request(params)
+          setAttributes(result)
+          return result
+        } catch (error) {
+          setAttributeError(error as Error)
+          throw error
+        } finally {
+          setIsRequestingAttributes(false)
+        }
+      },
+      []
+    )
+
+    const requestOpenIdAttributes = useCallback(
+      async (params: RequestOpenIdIdentityAttributesParameters) => {
+        setIsRequestingAttributes(true)
+        setAttributeError(null)
+        try {
+          const result = await identityAttributes.requestOpenId(params)
+          setAttributes(result)
+          return result
+        } catch (error) {
+          setAttributeError(error as Error)
+          throw error
+        } finally {
+          setIsRequestingAttributes(false)
+        }
+      },
+      []
+    )
+
+    const clearAttributes = useCallback(() => {
+      setAttributes(null)
+      setAttributeError(null)
+    }, [])
+
+    return {
+      requestAttributes,
+      requestOpenIdAttributes,
+      attributes,
+      isRequestingAttributes,
+      attributeError,
+      clearAttributes,
+    }
+  }
+
+  return { useIdentityAttributes }
+}

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

@@ -0,0 +1,136 @@
+import type {
+  AuthClientLike,
+  IdentityAttributeNonce,
+  IdentityAttributeResult,
+  RequestIdentityAttributesParameters,
+  RequestOpenIdIdentityAttributesParameters,
+} from "./types.js"
+
+import { AuthenticationManager } from "./authentication-manager.js"
+import {
+  decodeIdentityAttributeValues,
+  identityAttributeKeys,
+  normalizeSignedIdentityAttributes,
+} from "./identity-attributes.js"
+
+/**
+ * Requests and decodes signed identity attributes for an authenticated
+ * Internet Identity session.
+ *
+ * Await `authentication.prepareClient()` once during startup (the `useAuth`
+ * hook already does) so that {@link request} can open the identity provider
+ * window synchronously from a click handler.
+ *
+ * @example
+ * ```ts
+ * const attributes = new IdentityAttributesManager(authentication)
+ * const result = await attributes.request({
+ *   keys: ["name"],
+ *   nonce: () => fetchNonceFromCanister(),
+ * })
+ * ```
+ */
+export class IdentityAttributesManager {
+  constructor(public readonly authentication: AuthenticationManager) {}
+
+  public request = async ({
+    keys,
+    nonce,
+    signIn = true,
+    maxTimeToLive,
+    targets,
+    ...clientOptions
+  }: RequestIdentityAttributesParameters): Promise<IdentityAttributeResult> => {
+    // Nothing may be awaited before `requestAttributes` / `signIn` are invoked:
+    // the ICRC-29 transport only opens the identity provider window while the
+    // browser still considers us inside the user gesture. `getPreparedClient`
+    // is synchronous whenever `prepareClient()` has run.
+    const preparedClient = this.authentication.getPreparedClient(clientOptions)
+    const authClient =
+      preparedClient ?? (await this.authentication.ensureClient(clientOptions))
+
+    if (!authClient) {
+      throw new Error(
+        "Authentication module is missing or failed to initialize. To request identity attributes, please install @icp-sdk/auth v7 or later, or provide a compatible authClient."
+      )
+    }
+
+    this.authentication.setAuthenticating()
+
+    try {
+      // `signIn` first: it opens the transport channel synchronously, and the
+      // attribute request then reuses that same channel and window.
+      const identityPromise = signIn
+        ? this.authentication.signInOrRecoverIdentity({
+            maxTimeToLive,
+            targets,
+          })
+        : Promise.resolve(authClient.getIdentity())
+      const requestPromise = authClient.requestAttributes({
+        keys,
+        nonce: toAuthClientNonce(authClient, 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 = ({
+    keys,
+    openIdProvider,
+    ...rest
+  }: RequestOpenIdIdentityAttributesParameters): Promise<IdentityAttributeResult> => {
+    // Called (not awaited) synchronously so the user gesture is preserved.
+    return this.request({
+      ...rest,
+      openIdProvider,
+      keys: identityAttributeKeys({ openIdProvider, keys }),
+    })
+  }
+}
+
+/**
+ * Bridges the two `@icp-sdk/auth` nonce contracts.
+ *
+ * v8 takes `() => Promise<Uint8Array>` (it journals the value so a redirect
+ * flow replays the same bytes); v7 takes `Uint8Array | Promise<Uint8Array>`.
+ * Both open the transport channel synchronously for the deferred forms, so we
+ * always hand over the deferred shape the installed client understands.
+ * `memoize` only exists from v8 onwards, which makes it a reliable marker.
+ */
+function toAuthClientNonce(
+  authClient: AuthClientLike,
+  nonce: IdentityAttributeNonce
+): Uint8Array | Promise<Uint8Array> | (() => Promise<Uint8Array>) {
+  const supportsNonceThunk = typeof authClient.memoize === "function"
+
+  if (supportsNonceThunk) {
+    return () => Promise.resolve(typeof nonce === "function" ? nonce() : nonce)
+  }
+
+  return Promise.resolve(typeof nonce === "function" ? nonce() : nonce)
+}

package/src/auth/identity-attributes.ts

@@ -0,0 +1,270 @@
+import { IDL } from "@icp-sdk/core/candid"
+
+import type {
+  IdentityAttributeOpenIdProvider,
+  IdentityAttributeValues,
+  SignedIdentityAttributes,
+} from "./types.js"
+import { IC_INTERNET_IDENTITY_PROVIDER } from "./constants.js"
+
+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.js"
+export * from "./identity-attributes-manager.js"
+export * from "./identity-attributes.js"
+export * from "./constants.js"
+export * from "./types.js"
+export * from "../hooks/createAuthHooks.js"
+export * from "./createIdentityAttributeHooks.js"