create-react-admin-template 0.0.0-stage → 0.1.0

package/template/src/authentication/controller.ts

@@ -0,0 +1,351 @@
+import { fnParseInternalRedirect } from '@/lib/navigationRedirect'
+import { fnResolveAuthenticationRedirect } from './redirect'
+import {
+  AuthenticationError,
+  type IAuthenticationAdapterContext,
+  type IAuthenticationCallbackInput,
+  type IAuthenticationChallenge,
+  type IAuthenticationChallengeResponseInput,
+  type IAuthenticationController,
+  type IAuthenticationSnapshot,
+  type ICreateAuthenticationControllerOptions,
+  type TAuthenticationAdapterResult,
+  type TAuthenticationPurpose,
+  type TAuthenticationStartInput,
+} from './types'
+
+function fnCreateAuthenticationError(
+  objCause: Error | undefined,
+  strCode: 'adapter_failed' | 'completion_failed' | 'navigation_failed',
+  strMessage: string
+) {
+  if (objCause instanceof AuthenticationError) return objCause
+  return new AuthenticationError(strCode, strMessage, { cause: objCause })
+}
+
+function fnValidateChallenge(objChallenge: IAuthenticationChallenge) {
+  if (
+    !objChallenge.strChallengeId.trim() ||
+    !objChallenge.strMethod.trim() ||
+    !Number.isFinite(objChallenge.nExpiresAt) ||
+    (objChallenge.nAttemptsRemaining !== undefined &&
+      (!Number.isSafeInteger(objChallenge.nAttemptsRemaining) ||
+        objChallenge.nAttemptsRemaining < 0)) ||
+    (objChallenge.nRetryAfterMs !== undefined &&
+      (!Number.isSafeInteger(objChallenge.nRetryAfterMs) ||
+        objChallenge.nRetryAfterMs < 0)) ||
+    objChallenge.arrMethods?.some(
+      (objMethod) => !objMethod.strMethod.trim() || !objMethod.strLabel.trim()
+    )
+  ) {
+    throw new AuthenticationError(
+      'invalid_challenge',
+      '认证服务返回了无效挑战。'
+    )
+  }
+}
+
+function fnFreezeChallenge(
+  objChallenge: IAuthenticationChallenge
+): IAuthenticationChallenge {
+  const arrMethods = objChallenge.arrMethods?.map((objMethod) =>
+    Object.freeze({ ...objMethod })
+  )
+  return Object.freeze({
+    ...objChallenge,
+    ...(arrMethods ? { arrMethods: Object.freeze(arrMethods) } : {}),
+  })
+}
+
+function fnValidateStartInput(objInput: TAuthenticationStartInput) {
+  if (!objInput.strProviderKey.trim()) {
+    throw new AuthenticationError('invalid_input', '认证提供方标识不能为空。')
+  }
+  if (
+    objInput.strPurpose === 'signIn' &&
+    objInput.strReturnPath !== undefined &&
+    fnParseInternalRedirect(objInput.strReturnPath) === undefined
+  ) {
+    throw new AuthenticationError(
+      'invalid_input',
+      '登录回跳地址必须是安全的站内路径。'
+    )
+  }
+  if (objInput.strPurpose === 'stepUp' && !objInput.strActionKey.trim()) {
+    throw new AuthenticationError('invalid_input', 'Step-up 操作标识不能为空。')
+  }
+}
+
+function fnValidateResultPurpose(
+  objResult: TAuthenticationAdapterResult,
+  strExpectedPurpose: TAuthenticationPurpose
+) {
+  const strResultPurpose =
+    objResult.strResult === 'complete'
+      ? objResult.objCompletion.strPurpose
+      : objResult.strPurpose
+  if (strResultPurpose !== strExpectedPurpose) {
+    throw new AuthenticationError(
+      'invalid_result',
+      '认证服务返回了与当前流程不匹配的结果。'
+    )
+  }
+
+  if (objResult.strResult !== 'complete') {
+    if (!objResult.strTransactionId.trim()) {
+      throw new AuthenticationError(
+        'invalid_result',
+        '认证服务没有返回有效事务标识。'
+      )
+    }
+    return
+  }
+
+  const objCompletion = objResult.objCompletion
+  if (
+    objCompletion.strPurpose === 'signIn' &&
+    (!objCompletion.objTokenResult.strAccessToken ||
+      !objCompletion.objTokenResult.strRefreshToken)
+  ) {
+    throw new AuthenticationError(
+      'invalid_result',
+      '认证服务没有返回有效登录结果。'
+    )
+  }
+  if (
+    objCompletion.strPurpose === 'stepUp' &&
+    (!objCompletion.objGrant.strGrantId.trim() ||
+      !Number.isFinite(objCompletion.objGrant.nExpiresAt) ||
+      (objCompletion.objGrant.strMode === 'requestToken' &&
+        !objCompletion.objGrant.strProofToken))
+  ) {
+    throw new AuthenticationError(
+      'invalid_result',
+      '认证服务没有返回有效 Step-up 授权。'
+    )
+  }
+}
+
+/** 创建不保存协议秘密、Token 或挑战响应的认证编排控制器。 */
+export function fnCreateAuthenticationController({
+  fnNavigateRedirect,
+  fnOnComplete,
+  objAdapter,
+  objRedirectPolicy,
+}: ICreateAuthenticationControllerOptions): IAuthenticationController {
+  const objListeners = new Set<() => void>()
+  let nOperation = 0
+  let objControllerAbort: AbortController | null = null
+  let objSnapshot: IAuthenticationSnapshot = Object.freeze({
+    nRevision: 0,
+    strStatus: 'idle',
+  })
+
+  const fnPublish = (objNext: Omit<IAuthenticationSnapshot, 'nRevision'>) => {
+    objSnapshot = Object.freeze({
+      ...objNext,
+      nRevision: objSnapshot.nRevision + 1,
+    })
+    objListeners.forEach((fnListener) => fnListener())
+    return objSnapshot
+  }
+
+  const fnBeginOperation = (
+    strPurpose: TAuthenticationPurpose,
+    strTransactionId?: string
+  ) => {
+    objControllerAbort?.abort()
+    const objAbortController = new AbortController()
+    objControllerAbort = objAbortController
+    const nCurrentOperation = ++nOperation
+    fnPublish({ strPurpose, strStatus: 'working', strTransactionId })
+    return { nCurrentOperation, objAbortController }
+  }
+
+  const fnIsCurrentOperation = (
+    nCurrentOperation: number,
+    objAbortController: AbortController
+  ) =>
+    nCurrentOperation === nOperation &&
+    objControllerAbort === objAbortController &&
+    !objAbortController.signal.aborted
+
+  const fnApplyResult = async (
+    objResult: TAuthenticationAdapterResult,
+    strPurpose: TAuthenticationPurpose,
+    nCurrentOperation: number,
+    objAbortController: AbortController
+  ) => {
+    if (!fnIsCurrentOperation(nCurrentOperation, objAbortController)) {
+      return objSnapshot
+    }
+    fnValidateResultPurpose(objResult, strPurpose)
+
+    if (objResult.strResult === 'challenge') {
+      fnValidateChallenge(objResult.objChallenge)
+      return fnPublish({
+        objChallenge: fnFreezeChallenge(objResult.objChallenge),
+        strPurpose,
+        strStatus: 'awaitingChallenge',
+        strTransactionId: objResult.strTransactionId,
+      })
+    }
+
+    if (objResult.strResult === 'redirect') {
+      const strRedirectUrl = fnResolveAuthenticationRedirect(
+        objResult.strRedirectUrl,
+        objRedirectPolicy
+      )
+      fnPublish({
+        strPurpose,
+        strStatus: 'redirecting',
+        strTransactionId: objResult.strTransactionId,
+      })
+      try {
+        await fnNavigateRedirect(strRedirectUrl)
+      } catch (objError) {
+        throw fnCreateAuthenticationError(
+          objError instanceof Error ? objError : undefined,
+          'navigation_failed',
+          '无法跳转到认证服务。'
+        )
+      }
+      return objSnapshot
+    }
+
+    try {
+      await fnOnComplete(objResult.objCompletion, {
+        objSignal: objAbortController.signal,
+      })
+    } catch (objError) {
+      throw fnCreateAuthenticationError(
+        objError instanceof Error ? objError : undefined,
+        'completion_failed',
+        '认证结果无法建立应用会话或恢复敏感操作。'
+      )
+    }
+    if (!fnIsCurrentOperation(nCurrentOperation, objAbortController)) {
+      return objSnapshot
+    }
+    return fnPublish({ strPurpose, strStatus: 'completed' })
+  }
+
+  const fnRunAdapterOperation = async (
+    strPurpose: TAuthenticationPurpose,
+    fnRequest: (
+      objContext: IAuthenticationAdapterContext
+    ) => Promise<TAuthenticationAdapterResult>,
+    strTransactionId?: string
+  ) => {
+    const { nCurrentOperation, objAbortController } = fnBeginOperation(
+      strPurpose,
+      strTransactionId
+    )
+    try {
+      const objResult = await fnRequest({
+        objSignal: objAbortController.signal,
+      })
+      return await fnApplyResult(
+        objResult,
+        strPurpose,
+        nCurrentOperation,
+        objAbortController
+      )
+    } catch (objError) {
+      if (!fnIsCurrentOperation(nCurrentOperation, objAbortController)) {
+        return objSnapshot
+      }
+      const objAuthenticationError = fnCreateAuthenticationError(
+        objError instanceof Error ? objError : undefined,
+        'adapter_failed',
+        '认证服务暂时不可用。'
+      )
+      return fnPublish({
+        objError: objAuthenticationError,
+        strPurpose,
+        strStatus: 'error',
+      })
+    } finally {
+      if (objControllerAbort === objAbortController) {
+        objControllerAbort = null
+      }
+    }
+  }
+
+  const objController: IAuthenticationController = {
+    fnGetSnapshot: () => objSnapshot,
+    fnSubscribe(fnListener) {
+      objListeners.add(fnListener)
+      return () => objListeners.delete(fnListener)
+    },
+    fnStart(objInput: TAuthenticationStartInput) {
+      return fnRunAdapterOperation(objInput.strPurpose, (objContext) => {
+        fnValidateStartInput(objInput)
+        return objAdapter.fnStart(objInput, objContext)
+      })
+    },
+    fnCompleteRedirect(objInput: IAuthenticationCallbackInput) {
+      return fnRunAdapterOperation(objInput.strPurpose, (objContext) =>
+        objAdapter.fnCompleteRedirect(objInput, objContext)
+      )
+    },
+    fnVerifyChallenge(objInput: IAuthenticationChallengeResponseInput) {
+      const objChallenge = objSnapshot.objChallenge
+      const strPurpose = objSnapshot.strPurpose
+      if (
+        objSnapshot.strStatus !== 'awaitingChallenge' ||
+        !objChallenge ||
+        !strPurpose ||
+        objInput.strChallengeId !== objChallenge.strChallengeId ||
+        objInput.strMethod !== objChallenge.strMethod
+      ) {
+        return Promise.resolve(
+          fnPublish({
+            objError: new AuthenticationError(
+              'invalid_state',
+              '当前没有可提交的认证挑战。'
+            ),
+            strPurpose,
+            strStatus: 'error',
+          })
+        )
+      }
+      return fnRunAdapterOperation(
+        strPurpose,
+        (objContext) => objAdapter.fnVerifyChallenge(objInput, objContext),
+        objSnapshot.strTransactionId
+      )
+    },
+    async fnCancel() {
+      const strPurpose = objSnapshot.strPurpose
+      const strTransactionId = objSnapshot.strTransactionId
+      objControllerAbort?.abort()
+      objControllerAbort = null
+      nOperation++
+      const objCancelledSnapshot = fnPublish({
+        strPurpose,
+        strStatus: 'cancelled',
+      })
+      if (objAdapter.fnCancel && strPurpose && strTransactionId) {
+        const objAbortController = new AbortController()
+        try {
+          await objAdapter.fnCancel(
+            { strPurpose, strTransactionId },
+            { objSignal: objAbortController.signal }
+          )
+        } catch {
+          // 本地取消优先，远端取消失败不恢复挑战、Token 或协议状态。
+        }
+      }
+      return objCancelledSnapshot
+    },
+    fnReset() {
+      objControllerAbort?.abort()
+      objControllerAbort = null
+      nOperation++
+      return fnPublish({ strStatus: 'idle' })
+    },
+  }
+
+  return objController
+}

package/template/src/authentication/index.ts

@@ -0,0 +1,8 @@
+export { fnCreateAuthenticationController } from './controller'
+export { fnResolveAuthenticationRedirect } from './redirect'
+export {
+  AuthenticationError,
+  type IAuthenticationAdapter,
+  type TAuthenticationAdapterResult,
+  type TAuthenticationCompletion,
+} from './types'

package/template/src/authentication/redirect.ts

@@ -0,0 +1,72 @@
+import {
+  AuthenticationError,
+  type IAuthenticationRedirectPolicy,
+} from './types'
+
+function fnParseOrigin(strOrigin: string, strFieldName: string) {
+  try {
+    const objUrl = new URL(strOrigin)
+    if (
+      !['http:', 'https:'].includes(objUrl.protocol) ||
+      objUrl.username ||
+      objUrl.password ||
+      objUrl.origin === 'null'
+    ) {
+      throw new Error('unsupported origin')
+    }
+    return objUrl
+  } catch (objError) {
+    throw new AuthenticationError(
+      'invalid_redirect',
+      `${strFieldName} 不是受支持的 HTTP(S) Origin。`,
+      { cause: objError instanceof Error ? objError : undefined }
+    )
+  }
+}
+
+/** 校验认证跳转协议、凭据、Fragment 和显式 Origin 白名单。 */
+export function fnResolveAuthenticationRedirect(
+  strRedirectUrl: string,
+  objPolicy: IAuthenticationRedirectPolicy
+) {
+  const objApplicationUrl = fnParseOrigin(
+    objPolicy.strApplicationOrigin,
+    'strApplicationOrigin'
+  )
+  const objAllowedOrigins = new Set([
+    objApplicationUrl.origin,
+    ...(objPolicy.arrAllowedOrigins ?? []).map(
+      (strOrigin) => fnParseOrigin(strOrigin, 'arrAllowedOrigins').origin
+    ),
+  ])
+
+  let objRedirectUrl: URL
+  try {
+    objRedirectUrl = new URL(strRedirectUrl, objApplicationUrl.origin)
+  } catch (objError) {
+    throw new AuthenticationError(
+      'invalid_redirect',
+      '认证服务返回了无效跳转地址。',
+      { cause: objError instanceof Error ? objError : undefined }
+    )
+  }
+
+  const bIsAllowedHttp =
+    objRedirectUrl.protocol === 'http:' &&
+    objApplicationUrl.protocol === 'http:' &&
+    objRedirectUrl.origin === objApplicationUrl.origin
+  if (
+    (objRedirectUrl.protocol !== 'https:' && !bIsAllowedHttp) ||
+    objRedirectUrl.username ||
+    objRedirectUrl.password ||
+    objRedirectUrl.hash ||
+    !objAllowedOrigins.has(objRedirectUrl.origin)
+  ) {
+    throw new AuthenticationError(
+      'invalid_redirect',
+      '认证跳转地址未通过协议或 Origin 白名单校验。'
+    )
+  }
+
+  return objRedirectUrl.toString()
+}