@world-engines/project-host 0.1.0-alpha.0

package/dist/local-gui-auth.d.ts

@@ -0,0 +1,96 @@
+import { type ScenarioTag } from "@world-engines/authoring-ui/score-tags";
+import type { ProjectTransferTransport } from "./transfer/transport.js";
+/** server 的 CSP form-action 必须复用此精确授权 origin 列表。 */
+export declare const LOCAL_GUI_AUTHORIZATION_ORIGINS: readonly string[];
+export type LocalGuiAuthState = "signed_out" | "challenge_pending" | "signed_in";
+export interface LocalGuiAuthStatus {
+    readonly state: LocalGuiAuthState;
+    readonly project_id: string;
+    readonly expires_at_ms?: number;
+}
+export interface LocalGuiAuthStart extends LocalGuiAuthStatus {
+    readonly state: "challenge_pending";
+    /** 只能导航到此 URL；既有 handoff 协议在 query 中包含 state，禁止记录。 */
+    readonly authorization_url: string;
+}
+/**
+ * 本地凭据清除和远端 handoff cancel 是两个独立的状态转换。
+ * remote_cancel 不携带 request/state 等 challenge identity，只告知 GUI 是否仍可由同一
+ * auth instance 重试取消。
+ */
+export type LocalGuiRemoteCancelOutcome = "not_required" | "confirmed" | "pending_retry";
+export interface LocalGuiLogoutResult extends LocalGuiAuthStatus {
+    readonly remote_cancel: LocalGuiRemoteCancelOutcome;
+}
+export interface LocalGuiAuth {
+    status(): LocalGuiAuthStatus;
+    account(): Promise<LocalGuiAccountStatus>;
+    start(): Promise<LocalGuiAuthStart>;
+    handleCallback(callbackUrl: string | URL): Promise<LocalGuiAuthStatus>;
+    logout(): Promise<LocalGuiLogoutResult>;
+    requestScore(request: LocalGuiScoreRequest): Promise<LocalGuiScoreResponse>;
+    /** 固定路由的账户模型调用；远端 HttpOnly session 永不离开此 closure。 */
+    requestModel(request: LocalGuiModelRequest): Promise<LocalGuiModelResponse>;
+    readonly transport: ProjectTransferTransport;
+}
+export interface LocalGuiAccountStatus extends LocalGuiAuthStatus {
+    readonly account?: {
+        readonly display_name?: string;
+        readonly balance_units?: string;
+        readonly profile_state: "ready" | "unavailable";
+        readonly wallet_state: "ready" | "unavailable";
+    };
+}
+declare const localGuiModelSessionLeaseBrand: unique symbol;
+/** 仅由登录 cookie closure 签发；运行时还会通过私有 WeakMap 校验，外部无法伪造。 */
+export interface LocalGuiModelSessionLease {
+    readonly [localGuiModelSessionLeaseBrand]: true;
+}
+export type LocalGuiModelRequest = Readonly<{
+    kind: "session";
+}> | Readonly<{
+    kind: "chat_catalog";
+    session: LocalGuiModelSessionLease;
+}> | Readonly<{
+    kind: "embedding_descriptor";
+    session: LocalGuiModelSessionLease;
+}> | Readonly<{
+    kind: "embedding";
+    session: LocalGuiModelSessionLease;
+    idempotency_key: string;
+    body: unknown;
+}> | Readonly<{
+    kind: "chat_completions";
+    session: LocalGuiModelSessionLease;
+    idempotency_key: string;
+    body: unknown;
+}>;
+export interface LocalGuiModelResponse {
+    readonly kind: LocalGuiModelRequest["kind"];
+    readonly status: number;
+    readonly body: Readonly<Record<string, unknown>>;
+    /** 仅 session kind 的成功响应存在；不是 credential，且只在签发它的 auth instance 内有效。 */
+    readonly session?: LocalGuiModelSessionLease;
+}
+export type LocalGuiScoreRequest = Readonly<{
+    kind: "score";
+}> | Readonly<{
+    kind: "tag-benchmark";
+    tag: ScenarioTag;
+}>;
+export interface LocalGuiScoreResponse {
+    readonly kind: LocalGuiScoreRequest["kind"];
+    readonly body: unknown;
+}
+export interface LocalGuiAuthOptions {
+    readonly projectId: string;
+    readonly loopbackOrigin: string;
+    /** 评分请求需要此根目录逐次校验当前 review target；其他认证操作不读取项目文件。 */
+    readonly projectRoot?: string;
+    readonly fetch?: typeof globalThis.fetch;
+    readonly openBrowser?: (authorizationUrl: string) => void | Promise<void>;
+}
+/** 为 npm GUI adapter 镜像 native broker 的 project-transfer route allowlist。 */
+export declare function isLocalGuiTransferRouteAllowed(method: string, path: string): boolean;
+export declare function createLocalGuiAuth(options: LocalGuiAuthOptions): LocalGuiAuth;
+export {};