openxiangda 1.0.84 → 1.0.86

package/openxiangda-skills/references/pages/page-sdk.md

@@ -14,6 +14,7 @@ Guidelines:
 - Use `sdk.function.invoke(code, { input })` for reusable backend business logic declared under `src/resources/functions/` and `src/functions/`. Do not implement multi-form orchestration, connector fan-out, notification orchestration, or permission-sensitive backend rules directly in a page component.
 - Use `sdk.connector.invoke`, `sdk.connector.call("connector.api")`, or `sdk.connector.download` for external services. The SDK calls the platform runtime connector endpoint; it must not call third-party domains directly.
 - Use `sdk.notification.sendByType` and `batchSendByType` for reusable business messages. Custom notification types must be declared in `src/resources/notifications/` and published with `openxiangda resource publish`.
+- Use `createAuthClient` from `openxiangda/runtime` or `LoginPage` / `useAuth` from `openxiangda/runtime/react` for application login pages. Auth provider App Functions return identity assertions only; platform auth owns create/bind/reject/token decisions.
 - For the current user's department hierarchy, use `sdk.department.getCurrentUserParentDepartments()`; do not hardcode `GET /department/:id/parentDepartments` in page code.
 - Use `sdk.auth.logoutAndRedirect({ loginUrl })` for user logout when the page should return after login. It calls the platform logout endpoint, appends the current page URL as `callback`, and redirects to the login URL. Use `sdk.auth.logout()` only when the page wants to handle redirect itself.
 - Use `sdk.role.getMyRoles()`, `sdk.role.getCurrentRole()`, and `sdk.role.switchAppRole()` for current-user app role switching. Pass `roleId: ""` to switch back to all app roles.
@@ -102,6 +103,44 @@ const result = await sdk.function.invoke("reservation_reminder_summary", {
 
 Use App Functions when the logic must run server-side and be reusable by pages, automations, or workflows. Current runtime invocation requires the caller to have app automation management permission; ordinary page users should normally consume function-backed data through a permission-aware page or a narrower backend resource.
 
+Application auth:
+
+```tsx
+import { LoginPage, useAuth, useLoginMethods } from "openxiangda/runtime/react";
+
+export function DefaultLogin() {
+  return <LoginPage />;
+}
+
+export function CustomPhoneLogin() {
+  const auth = useAuth();
+  const methods = useLoginMethods();
+
+  async function submit(phone: string, code: string, challengeId: string) {
+    await auth.phoneCodeLogin({ phone, code, challengeId });
+  }
+
+  return null;
+}
+```
+
+Standalone client:
+
+```ts
+import { createAuthClient } from "openxiangda/runtime";
+
+const auth = createAuthClient({ appType, servicePrefix: "/service" });
+const methods = await auth.getMethods();
+const sent = await auth.sendPhoneCode({ phone, purpose: "login" });
+const result = await auth.phoneCodeLogin({
+  phone,
+  code,
+  challengeId: sent.challengeId,
+});
+```
+
+For phone-code auth, the App Function provider receives `event`, `appType`, `method`, `credential`, `requestId`, `request`, and `challenge`. It may return `{ ok, providerState }` for send and `{ ok, identity }` for verify. It must not return `token`, `accessToken`, `refreshToken`, cookies, or mutate platform account tables.
+
 Logout and current-user role switching:
 
 ```ts

package/openxiangda-skills/references/resource-manifest-cheatsheet.md

@@ -9,6 +9,7 @@
 - **平台 ID 由 CLI 解析**：`openxiangda resource publish --profile <name>` 把 code 解析成当前 profile 的真实 ID 并写回 `.openxiangda/state.json`。
 - **永远不写密钥**：第三方 API key、token、secret、password、authorization、headers 等绝不出现在 `src/resources/`，平台管理员在后台配置。
 - **多 profile 不共享 ID**：`dev` / `prod` 各自维护一份资源 ID 映射，复制 manifest 即可复用，不要复制平台 ID。
+- **Auth provider 只返回身份声明**：登录 provider App Function 不能发 token、写 cookie、直接改用户表或绑定表；平台按策略创建/绑定/拒绝。
 
 ## 命令
 
@@ -20,6 +21,86 @@ openxiangda resource publish  --profile <name> --prune  # 删除 manifest 未声
 openxiangda resource pull     --profile <name>          # 拉取平台资源回写到本地（用于初次同步）
 ```
 
+## 0. Auth — `src/resources/auth/<code>.json`
+
+```json
+{
+  "code": "default",
+  "name": "Default App Login",
+  "status": "active",
+  "configJson": {
+    "methods": [
+      { "type": "password", "enabled": true, "label": "账号密码" },
+      { "type": "dingtalk", "enabled": true, "label": "钉钉免登" },
+      { "type": "sso", "enabled": true, "label": "CAS", "protocol": "cas" },
+      {
+        "type": "phone_code",
+        "enabled": true,
+        "label": "手机号验证码",
+        "ttlSeconds": 300,
+        "sendFrequencySeconds": 60,
+        "maxAttempts": 5,
+        "provider": { "functionCode": "auth_phone_code" }
+      }
+    ],
+    "registration": { "mode": "reject" },
+    "binding": { "mode": "auto" },
+    "matching": {
+      "keys": ["phone", "email", "externalId", "unionId", "jobNumber", "username"]
+    },
+    "defaultRoleCodes": []
+  }
+}
+```
+
+Provider function:
+
+```ts
+export default async function authPhoneCodeProvider(ctx, input) {
+  if (input.event === "phone_code.send") {
+    return { ok: true, providerState: { nonce: "vendor-message-id" } };
+  }
+
+  if (input.event === "phone_code.verify") {
+    if (input.credential.code !== "123456") {
+      return { ok: false, message: "验证码错误" };
+    }
+    return {
+      ok: true,
+      identity: {
+        phone: input.credential.phone,
+        externalId: `phone:${input.credential.phone}`
+      }
+    };
+  }
+
+  return { ok: false, message: "不支持的认证事件" };
+}
+```
+
+React 默认页：
+
+```tsx
+import { LoginPage } from "openxiangda/runtime/react";
+
+export default function AppLogin() {
+  return <LoginPage />;
+}
+```
+
+自定义登录页：
+
+```ts
+import { createAuthClient } from "openxiangda/runtime";
+
+const auth = createAuthClient({ appType, servicePrefix: "/service" });
+const methods = await auth.getMethods();
+const sent = await auth.sendPhoneCode({ phone, purpose: "login" });
+await auth.phoneCodeLogin({ phone, code, challengeId: sent.challengeId });
+```
+
+设计前必须确认启用方式、注册策略、身份匹配键、provider 边界、默认权限、安全参数、第三方配置归属。
+
 ## 1. Connector — `src/resources/connectors/<code>.json`
 
 ```json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openxiangda",
-  "version": "1.0.84",
+  "version": "1.0.86",
   "description": "OpenXiangda CLI, workspace build tools, runtime SDK, and form components.",
   "private": false,
   "bin": {
@@ -65,6 +65,7 @@
     "prepack": "npm run build:sdk",
     "test:profile-isolation": "bash scripts/profile-isolation-smoke.sh",
     "test:resource-plan": "node scripts/resource-plan-smoke.mjs",
+    "test:app-function-fallback": "node scripts/app-function-source-fallback-smoke.mjs",
     "test:runtime-deploy": "node scripts/runtime-deploy-smoke.mjs",
     "test:skill-install": "bash scripts/skill-install-smoke.sh",
     "test:workspace-init": "bash scripts/workspace-init-smoke.sh"

package/packages/sdk/dist/openxiangdaProvider-CaXMpsnK.d.mts

@@ -0,0 +1,328 @@
+import React__default, { CSSProperties } from 'react';
+
+type AuthMethodType = "password" | "dingtalk" | "sso" | "guest" | "phone_code" | string;
+interface AuthMethod {
+    type: AuthMethodType;
+    enabled?: boolean;
+    label?: string;
+    protocol?: string;
+    [key: string]: unknown;
+}
+interface LoginMethodsResult {
+    appType: string;
+    configCode?: string;
+    methods: AuthMethod[];
+    registration?: {
+        mode?: string;
+        [key: string]: unknown;
+    };
+    security?: {
+        hideFailureReason?: boolean;
+        [key: string]: unknown;
+    };
+    defaultRedirectUrl?: string;
+}
+interface AuthUser {
+    id: string;
+    username?: string;
+    name?: string;
+    phone?: string | null;
+    email?: string | null;
+    avatar?: string | null;
+    jobNumber?: string | null;
+    departments?: Array<Record<string, unknown>>;
+    affiliatedDepartmentId?: string | null;
+    affiliatedDepartment?: Record<string, unknown> | null;
+    [key: string]: unknown;
+}
+interface AuthTokenData {
+    accessToken: string;
+    refreshToken: string;
+    token?: string;
+    accessTokenExpiresAt?: number;
+    refreshTokenExpiresAt?: number;
+    user?: AuthUser;
+    guestUser?: AuthUser;
+    [key: string]: unknown;
+}
+interface PhoneCodeSendResult {
+    challengeId: string;
+    expiresAt?: string | Date;
+    ttlSeconds?: number;
+    message?: string;
+}
+interface SsoLoginUrlResult {
+    loginUrl: string;
+    protocol?: string;
+}
+interface AuthClientOptions {
+    appType: string;
+    servicePrefix?: string;
+    fetchImpl?: typeof fetch;
+}
+interface PasswordLoginInput {
+    username: string;
+    password: string;
+    clientFingerprint?: string;
+    challengeId?: string;
+    challengeAnswer?: string;
+}
+interface DingTalkLoginInput {
+    code: string;
+    corpId?: string;
+}
+interface GuestLoginInput {
+    guestIdentifier?: string;
+    domain?: string;
+    ipAddress?: string;
+    userAgent?: string;
+    formUuid?: string;
+}
+interface PhoneCodeInput {
+    phone: string;
+    purpose?: "login" | "register" | string;
+}
+interface PhoneCodeLoginInput {
+    phone: string;
+    code: string;
+    challengeId?: string;
+}
+interface PhoneCodeRegisterInput extends PhoneCodeLoginInput {
+    name?: string;
+    email?: string;
+}
+interface SsoLoginUrlInput {
+    protocol?: string;
+    redirectUri?: string;
+}
+interface RefreshInput {
+    refreshToken?: string;
+}
+interface ResolveLoginUrlInput {
+    callbackUrl?: string;
+    callbackParamName?: string;
+    loginUrl?: string;
+}
+interface AppAuthClient {
+    appType: string;
+    servicePrefix: string;
+    getMethods: () => Promise<LoginMethodsResult>;
+    passwordLogin: (input: PasswordLoginInput) => Promise<AuthTokenData>;
+    dingtalkLogin: (input: DingTalkLoginInput) => Promise<AuthTokenData>;
+    guestLogin: (input?: GuestLoginInput) => Promise<AuthTokenData>;
+    sendPhoneCode: (input: PhoneCodeInput) => Promise<PhoneCodeSendResult>;
+    phoneCodeLogin: (input: PhoneCodeLoginInput) => Promise<AuthTokenData>;
+    registerWithPhoneCode: (input: PhoneCodeRegisterInput) => Promise<AuthTokenData>;
+    getSsoLoginUrl: (input?: SsoLoginUrlInput) => Promise<SsoLoginUrlResult>;
+    refresh: (input?: RefreshInput) => Promise<AuthTokenData>;
+    logout: () => Promise<void>;
+    resolveLoginUrl: (input?: ResolveLoginUrlInput) => string;
+}
+declare class AuthClientError extends Error {
+    status?: number;
+    code?: number | string;
+    payload?: unknown;
+    constructor(message: string, options?: {
+        status?: number;
+        code?: number | string;
+        payload?: unknown;
+    });
+}
+declare const createAuthClient: ({ appType, servicePrefix, fetchImpl, }: AuthClientOptions) => AppAuthClient;
+
+interface UseAuthOptions extends Partial<AuthClientOptions> {
+}
+interface UseLoginMethodsState {
+    data: LoginMethodsResult | null;
+    methods: AuthMethod[];
+    loading: boolean;
+    error: Error | null;
+    reload: () => Promise<void>;
+}
+interface LoginPageProps extends UseAuthOptions {
+    title?: React__default.ReactNode;
+    subtitle?: React__default.ReactNode;
+    className?: string;
+    style?: CSSProperties;
+    defaultMethod?: "password" | "phone_code";
+    redirectUrl?: string;
+    redirectOnSuccess?: boolean;
+    onSuccess?: (data: AuthTokenData) => void | Promise<void>;
+}
+declare const useAuth: (options?: UseAuthOptions) => {
+    client: AppAuthClient;
+    getMethods: () => Promise<LoginMethodsResult>;
+    passwordLogin: (input: PasswordLoginInput) => Promise<AuthTokenData>;
+    dingtalkLogin: (input: DingTalkLoginInput) => Promise<AuthTokenData>;
+    guestLogin: (input?: GuestLoginInput) => Promise<AuthTokenData>;
+    sendPhoneCode: (input: PhoneCodeInput) => Promise<PhoneCodeSendResult>;
+    phoneCodeLogin: (input: PhoneCodeLoginInput) => Promise<AuthTokenData>;
+    registerWithPhoneCode: (input: PhoneCodeRegisterInput) => Promise<AuthTokenData>;
+    getSsoLoginUrl: (input?: SsoLoginUrlInput) => Promise<SsoLoginUrlResult>;
+    refresh: (input?: RefreshInput) => Promise<AuthTokenData>;
+    logout: () => Promise<void>;
+    resolveLoginUrl: (input?: ResolveLoginUrlInput) => string;
+};
+declare const useLoginMethods: (options?: UseAuthOptions) => UseLoginMethodsState;
+declare const LoginPage: React__default.FC<LoginPageProps>;
+
+type RuntimeErrorType = "unauthenticated" | "forbidden" | "network" | "unknown";
+type RuntimeRequestError = Error & {
+    type?: RuntimeErrorType;
+    status?: number;
+    code?: number | string;
+    payload?: unknown;
+};
+interface RuntimeErrorSnapshot {
+    type: RuntimeErrorType;
+    status?: number;
+    code?: number | string;
+    message: string;
+    payload?: unknown;
+}
+declare class RuntimeHttpError extends Error {
+    type: RuntimeErrorType;
+    status?: number;
+    code?: number | string;
+    payload?: unknown;
+    constructor(snapshot: RuntimeErrorSnapshot);
+}
+interface RuntimeMenuItem {
+    id: string;
+    name: string;
+    resourceCode?: string | null;
+    routeCode?: string | null;
+    path?: string | null;
+    type?: string;
+    formUuid?: string | null;
+    pageId?: string | null;
+    parentId?: string | null;
+    sortOrder?: number;
+    isHidden?: boolean;
+    icon?: string | null;
+    children?: RuntimeMenuItem[];
+    [key: string]: unknown;
+}
+interface RuntimePagePermissions {
+    appType: string;
+    hasFullAccess: boolean;
+    roleCodes: string[];
+    roleSource?: string;
+    menuFormUuids: string[];
+    menuCodes: string[];
+    routeCodes: string[];
+    pathPatterns: string[];
+}
+interface RuntimeBootstrap {
+    appType: string;
+    app?: Record<string, unknown> | null;
+    user?: Record<string, unknown> | null;
+    runtime?: {
+        mode?: "legacy" | "react-spa" | string;
+        settings?: Record<string, unknown>;
+        activeReleaseId?: string | null;
+        activeBuildId?: string | null;
+        indexUrl?: string | null;
+        assetBaseUrl?: string | null;
+    };
+    permissions?: RuntimePagePermissions;
+    menus?: RuntimeMenuItem[];
+    servicePrefix?: string;
+}
+interface RouteAccessResult {
+    appType: string;
+    canAccess: boolean;
+    routeCode?: string;
+    menuCode?: string;
+    path?: string;
+    status?: number;
+    code?: number | string;
+    message?: string;
+    errorType?: RuntimeErrorType;
+    payload?: unknown;
+    permissions?: RuntimePagePermissions;
+}
+interface RuntimeRequestState<T> {
+    data: T | null;
+    loading: boolean;
+    error: RuntimeRequestError | null;
+}
+interface OpenXiangdaProviderProps {
+    appType?: string;
+    servicePrefix?: string;
+    fetchImpl?: typeof fetch;
+    children: React__default.ReactNode;
+}
+interface OpenXiangdaRuntimeStore extends RuntimeRequestState<RuntimeBootstrap> {
+    appType: string;
+    servicePrefix: string;
+    fetchImpl: typeof fetch;
+    reload: () => Promise<void>;
+}
+declare const OpenXiangdaProvider: React__default.FC<OpenXiangdaProviderProps>;
+declare const useOpenXiangda: () => OpenXiangdaRuntimeStore;
+declare const useRuntimeBootstrap: () => OpenXiangdaRuntimeStore;
+declare const useAppMenus: () => {
+    data: RuntimeMenuItem[];
+    appType: string;
+    servicePrefix: string;
+    fetchImpl: typeof fetch;
+    reload: () => Promise<void>;
+    loading: boolean;
+    error: RuntimeRequestError | null;
+};
+declare const usePermission: () => {
+    data: RuntimePagePermissions | null;
+    appType: string;
+    servicePrefix: string;
+    fetchImpl: typeof fetch;
+    reload: () => Promise<void>;
+    loading: boolean;
+    error: RuntimeRequestError | null;
+};
+interface UseCanAccessRouteInput {
+    routeCode?: string;
+    menuCode?: string;
+    path?: string;
+}
+declare const useCanAccessRoute: (input: UseCanAccessRouteInput) => {
+    canAccess: boolean;
+    data: RouteAccessResult | null;
+    loading: boolean;
+    error: RuntimeRequestError | null;
+};
+interface PermissionBoundaryProps extends UseCanAccessRouteInput {
+    children: React__default.ReactNode;
+    fallback?: React__default.ReactNode | PermissionBoundaryFallback;
+    loadingFallback?: React__default.ReactNode | PermissionBoundaryFallback;
+}
+interface PermissionBoundaryFallbackState {
+    access: ReturnType<typeof useCanAccessRoute>;
+    runtime: ReturnType<typeof useOpenXiangda>;
+    error: RuntimeRequestError | null;
+    errorType: RuntimeErrorType;
+    status?: number;
+    code?: number | string;
+    message: string;
+}
+type PermissionBoundaryFallback = (state: PermissionBoundaryFallbackState) => React__default.ReactNode;
+declare const PermissionBoundary: React__default.FC<PermissionBoundaryProps>;
+interface RuntimeResolveLoginOptions {
+    redirectUri?: string;
+    loginUrl?: string;
+    domain?: string;
+}
+interface RuntimeRedirectLoginOptions extends RuntimeResolveLoginOptions {
+    replace?: boolean;
+}
+interface RuntimeLogoutOptions extends RuntimeRedirectLoginOptions {
+    continueOnError?: boolean;
+}
+declare const useRuntimeAuth: () => {
+    logout: () => Promise<any>;
+    logoutAndRedirect: (options?: RuntimeLogoutOptions) => Promise<string>;
+    redirectToLogin: (options?: RuntimeRedirectLoginOptions) => Promise<string>;
+    resolveLoginUrl: (options?: RuntimeResolveLoginOptions) => Promise<string>;
+};
+
+export { type AppAuthClient as A, type RuntimeRedirectLoginOptions as B, type RuntimeRequestError as C, type DingTalkLoginInput as D, type RuntimeRequestState as E, type RuntimeResolveLoginOptions as F, type GuestLoginInput as G, type SsoLoginUrlResult as H, type UseCanAccessRouteInput as I, type UseLoginMethodsState as J, createAuthClient as K, type LoginMethodsResult as L, useAppMenus as M, useAuth as N, OpenXiangdaProvider as O, type PasswordLoginInput as P, useCanAccessRoute as Q, type RefreshInput as R, type SsoLoginUrlInput as S, useLoginMethods as T, type UseAuthOptions as U, useOpenXiangda as V, usePermission as W, useRuntimeAuth as X, useRuntimeBootstrap as Y, AuthClientError as a, type AuthClientOptions as b, type AuthMethod as c, type AuthMethodType as d, type AuthTokenData as e, type AuthUser as f, LoginPage as g, type LoginPageProps as h, type OpenXiangdaProviderProps as i, PermissionBoundary as j, type PermissionBoundaryFallback as k, type PermissionBoundaryFallbackState as l, type PermissionBoundaryProps as m, type PhoneCodeInput as n, type PhoneCodeLoginInput as o, type PhoneCodeRegisterInput as p, type PhoneCodeSendResult as q, type ResolveLoginUrlInput as r, type RouteAccessResult as s, type RuntimeBootstrap as t, type RuntimeErrorSnapshot as u, type RuntimeErrorType as v, RuntimeHttpError as w, type RuntimeLogoutOptions as x, type RuntimeMenuItem as y, type RuntimePagePermissions as z };