trustbase-seller-backend 0.7.0 → 0.7.2

package/middleware/scope-auth.d.ts

@@ -1,54 +1,54 @@
-/**
- * Scope Auth Middleware — 数据租客原则的核心执行层 (PRD-NEW §27.6/§27.7)
- *
- * 用户是房东,应用是租客。requireScope 是「检查租客有没有这把钥匙」的门卫。
- *
- * Token 优先级:
- *   1. 第三方 OAuth token (OAuthPlugin.validateAccessToken) → 严格 scope 强制
- *   2. 第一方登录 token (AuthPlugin.verifyToken) → 隐式全权限(用户自己的 session)
- *
- * 第一方 = 隐式全权限:用户自己登录操作自己的数据,不受 scope 限制。
- * 第三方 = 严格 scope:App 只能访问用户授权的 scope(逐项 toggle 的子集)。
- */
-import { Request, Response, NextFunction } from 'express';
-import type { OAuthPlugin } from '../plugins/oauth';
-import type { AuthPlugin } from '../plugins/auth';
-import type { IssuerKeyCache } from '../oauth/issuer-keys';
-import type { RevocationStore } from '../oauth/revocation-store';
-export interface OAuthUser {
-    userId: string;
-    address: string;
-    scopes: string[];
-    isOAuth: boolean;
-    clientId?: string;
-    tokenV2?: boolean;
-}
-/** R2-1: tv2 离线验证依赖（注入即启用；不注入则 tv2 token 一律 401） */
-export interface ScopeAuthV2Deps {
-    issuerKeys: IssuerKeyCache;
-    revocations: RevocationStore;
-}
-declare module 'express-serve-static-core' {
-    interface Request {
-        oauthUser?: OAuthUser;
-        walletAddress?: string;
-    }
-}
-/**
- * 写操作钱包挑战（R2-1 设计 §4 + R2-2 预研方案 B）：写/高危操作必须叠加 walletAuth，
- * 且签名者 === token 当事人（tv2=sub；第一方=用户地址）。token 丢了没有用户私钥
- * 照样用不了写操作。
- * 用法：router.post('/write-op', walletAuth(), requireScope('x:write'), requireWalletSubMatch(), handler)
- * （walletAuth 在前，requireScope 在后。）
- *
- * 管辖范围（R2-2 方案 B，预研实现，待 kimi 拍板）：
- * - tv2 token（tokenV2=true）→ 强制 walletAuth + signer===sub（R2-1 已有）
- * - 第一方登录 token（isOAuth=false）→ 强制 walletAuth + signer===address
- *   收口"隐式全权限"：第三方 App 即使拿到第一方 token 也做不了写操作。
- *   不做 scope 检查——第一方默认 scopes 只有 profile/email，加检查会破坏
- *   所有依赖第一方全权限的现有端点（orders/marketplace 等）。
- * - v1 第三方 OAuth token（isOAuth=true 非 tv2）→ 保持豁免（本就有严格 scope 制）
- */
-export declare function requireWalletSubMatch(): (req: Request, res: Response, next: NextFunction) => void | Response<any, Record<string, any>>;
-export declare function createScopeAuth(oauthPlugin: OAuthPlugin, authPlugin: AuthPlugin, v2Deps?: ScopeAuthV2Deps): (scope: string) => (req: Request, res: Response, next: NextFunction) => Promise<void | Response<any, Record<string, any>>>;
+/**
+ * Scope Auth Middleware — 数据租客原则的核心执行层 (PRD-NEW §27.6/§27.7)
+ *
+ * 用户是房东,应用是租客。requireScope 是「检查租客有没有这把钥匙」的门卫。
+ *
+ * Token 优先级:
+ *   1. 第三方 OAuth token (OAuthPlugin.validateAccessToken) → 严格 scope 强制
+ *   2. 第一方登录 token (AuthPlugin.verifyToken) → 隐式全权限(用户自己的 session)
+ *
+ * 第一方 = 隐式全权限:用户自己登录操作自己的数据,不受 scope 限制。
+ * 第三方 = 严格 scope:App 只能访问用户授权的 scope(逐项 toggle 的子集)。
+ */
+import { Request, Response, NextFunction } from 'express';
+import type { OAuthPlugin } from '../plugins/oauth';
+import type { AuthPlugin } from '../plugins/auth';
+import type { IssuerKeyCache } from '../oauth/issuer-keys';
+import type { RevocationStore } from '../oauth/revocation-store';
+export interface OAuthUser {
+    userId: string;
+    address: string;
+    scopes: string[];
+    isOAuth: boolean;
+    clientId?: string;
+    tokenV2?: boolean;
+}
+/** R2-1: tv2 离线验证依赖（注入即启用；不注入则 tv2 token 一律 401） */
+export interface ScopeAuthV2Deps {
+    issuerKeys: IssuerKeyCache;
+    revocations: RevocationStore;
+}
+declare module 'express-serve-static-core' {
+    interface Request {
+        oauthUser?: OAuthUser;
+        walletAddress?: string;
+    }
+}
+/**
+ * 写操作钱包挑战（R2-1 设计 §4 + R2-2 预研方案 B）：写/高危操作必须叠加 walletAuth，
+ * 且签名者 === token 当事人（tv2=sub；第一方=用户地址）。token 丢了没有用户私钥
+ * 照样用不了写操作。
+ * 用法：router.post('/write-op', walletAuth(), requireScope('x:write'), requireWalletSubMatch(), handler)
+ * （walletAuth 在前，requireScope 在后。）
+ *
+ * 管辖范围（R2-2 方案 B，预研实现，待 kimi 拍板）：
+ * - tv2 token（tokenV2=true）→ 强制 walletAuth + signer===sub（R2-1 已有）
+ * - 第一方登录 token（isOAuth=false）→ 强制 walletAuth + signer===address
+ *   收口"隐式全权限"：第三方 App 即使拿到第一方 token 也做不了写操作。
+ *   不做 scope 检查——第一方默认 scopes 只有 profile/email，加检查会破坏
+ *   所有依赖第一方全权限的现有端点（orders/marketplace 等）。
+ * - v1 第三方 OAuth token（isOAuth=true 非 tv2）→ 保持豁免（本就有严格 scope 制）
+ */
+export declare function requireWalletSubMatch(): (req: Request, res: Response, next: NextFunction) => void | Response<any, Record<string, any>>;
+export declare function createScopeAuth(oauthPlugin: OAuthPlugin, authPlugin: AuthPlugin, v2Deps?: ScopeAuthV2Deps): (scope: string) => (req: Request, res: Response, next: NextFunction) => Promise<void | Response<any, Record<string, any>>>;
 //# sourceMappingURL=scope-auth.d.ts.map

package/middleware/scope-auth.js

@@ -1,153 +1,153 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.requireWalletSubMatch = requireWalletSubMatch;
-exports.createScopeAuth = createScopeAuth;
-const token_v2_1 = require("../oauth/token-v2");
-/**
- * 写操作钱包挑战（R2-1 设计 §4 + R2-2 预研方案 B）：写/高危操作必须叠加 walletAuth，
- * 且签名者 === token 当事人（tv2=sub；第一方=用户地址）。token 丢了没有用户私钥
- * 照样用不了写操作。
- * 用法：router.post('/write-op', walletAuth(), requireScope('x:write'), requireWalletSubMatch(), handler)
- * （walletAuth 在前，requireScope 在后。）
- *
- * 管辖范围（R2-2 方案 B，预研实现，待 kimi 拍板）：
- * - tv2 token（tokenV2=true）→ 强制 walletAuth + signer===sub（R2-1 已有）
- * - 第一方登录 token（isOAuth=false）→ 强制 walletAuth + signer===address
- *   收口"隐式全权限"：第三方 App 即使拿到第一方 token 也做不了写操作。
- *   不做 scope 检查——第一方默认 scopes 只有 profile/email，加检查会破坏
- *   所有依赖第一方全权限的现有端点（orders/marketplace 等）。
- * - v1 第三方 OAuth token（isOAuth=true 非 tv2）→ 保持豁免（本就有严格 scope 制）
- */
-function requireWalletSubMatch() {
-    return (req, res, next) => {
-        const ou = req.oauthUser;
-        if (!ou)
-            return next();
-        // 豁免: v1 第三方 token (严格 scope 制已管), 不在本中间件管辖
-        if (ou.isOAuth && !ou.tokenV2)
-            return next();
-        if (!req.walletAddress) {
-            return res.status(401).json({
-                error: 'wallet-challenge-required',
-                message: ou.tokenV2 ? 'write op with tv2 token requires walletAuth headers' : 'write op with first-party token requires walletAuth headers',
-            });
-        }
-        if (req.walletAddress !== ou.address) {
-            return res.status(403).json({ error: 'wallet-sub-mismatch', message: 'signer must equal token subject' });
-        }
-        next();
-    };
-}
-function createScopeAuth(oauthPlugin, authPlugin, v2Deps) {
-    /**
-     * requireScope(scope) — 路由级中间件,校验 token 是否持有指定 scope。
-     *
-     * 第一方 token 隐式通过(用户自己 = 全权限)。
-     * 第三方 token 必须 scopes.includes(scope),否则 403 insufficient_scope。
-     */
-    return function requireScope(scope) {
-        return async (req, res, next) => {
-            const authHeader = req.headers.authorization;
-            if (!authHeader || !authHeader.startsWith('Bearer ')) {
-                return res.status(401).json({ error: 'missing_token', message: 'Authorization Bearer token required' });
-            }
-            const token = authHeader.substring(7);
-            // 0. tv2 结构化令牌 → 跨索引器离线验证（R2-1）
-            //    不查本地用户表（B 节点没有该用户行），sub 即身份。
-            if (token.startsWith(token_v2_1.TOKEN_V2_PREFIX)) {
-                if (!v2Deps) {
-                    return res.status(401).json({ error: 'token-v2-not-enabled' });
-                }
-                let issuerPubkey;
-                const parsed = (0, token_v2_1.parseTokenV2)(token);
-                if (!parsed) {
-                    return res.status(401).json({ error: 'invalid_token', message: 'malformed tv2 token' });
-                }
-                try {
-                    issuerPubkey = await v2Deps.issuerKeys.get(parsed.payload.iss);
-                }
-                catch {
-                    return res.status(503).json({ error: 'issuer-key-unavailable', message: 'chain query failed and no cached key' });
-                }
-                if (!issuerPubkey) {
-                    return res.status(401).json({ error: 'unknown-issuer' });
-                }
-                const verdict = await (0, token_v2_1.verifyTokenV2Offline)(token, issuerPubkey, v2Deps.revocations);
-                if (!verdict.ok) {
-                    return res.status(401).json({ error: 'invalid_token', reason: verdict.reason });
-                }
-                const p = verdict.payload;
-                if (!p.scopes.includes(scope)) {
-                    return res.status(403).json({ error: 'insufficient_scope', required: scope, granted: p.scopes });
-                }
-                req.oauthUser = {
-                    userId: p.sub,
-                    address: p.sub,
-                    scopes: p.scopes,
-                    isOAuth: true,
-                    clientId: p.client_id,
-                    tokenV2: true,
-                };
-                res.on('finish', () => {
-                    oauthPlugin.logAccess({
-                        appName: '', clientId: p.client_id,
-                        userId: p.sub, userAddress: p.sub,
-                        endpoint: req.path, method: req.method,
-                        scopeUsed: scope, responseStatus: res.statusCode,
-                    }).catch(() => { });
-                });
-                return next();
-            }
-            // 1. 先试第三方 OAuth token
-            const oauthInfo = await oauthPlugin.validateAccessToken(token);
-            if (oauthInfo) {
-                // 第三方 → 严格 scope 强制
-                if (!oauthInfo.scopes.includes(scope)) {
-                    return res.status(403).json({ error: 'insufficient_scope', required: scope, granted: oauthInfo.scopes });
-                }
-                // 解析 address
-                const user = await authPlugin.getUser(oauthInfo.userId);
-                if (!user) {
-                    return res.status(401).json({ error: 'invalid_token', message: 'User not found' });
-                }
-                req.oauthUser = {
-                    userId: oauthInfo.userId,
-                    address: user.address,
-                    scopes: oauthInfo.scopes,
-                    isOAuth: true,
-                    clientId: oauthInfo.clientId,
-                };
-                // 访问日志(PRD §27.9):仅第三方 OAuth token 记录,第一方不记
-                const appName = ''; // app_name 需要 JOIN 查,这里只记 endpoint/scope
-                res.on('finish', () => {
-                    oauthPlugin.logAccess({
-                        appName, clientId: oauthInfo.clientId,
-                        userId: oauthInfo.userId, userAddress: user.address,
-                        endpoint: req.path, method: req.method,
-                        scopeUsed: scope, responseStatus: res.statusCode,
-                    }).catch(() => { });
-                });
-                return next();
-            }
-            // 2. 后试第一方登录 token
-            const sessionInfo = await authPlugin.verifyToken(token);
-            if (sessionInfo) {
-                // 第一方 → 隐式全权限(用户自己的 session)
-                const user = await authPlugin.getUser(sessionInfo.userId);
-                if (!user) {
-                    return res.status(401).json({ error: 'invalid_token', message: 'User not found' });
-                }
-                req.oauthUser = {
-                    userId: sessionInfo.userId,
-                    address: user.address,
-                    scopes: sessionInfo.scopes,
-                    isOAuth: false,
-                };
-                return next();
-            }
-            // 3. 都不匹配 → 无效 token
-            return res.status(401).json({ error: 'invalid_token', message: 'Token not recognized or expired' });
-        };
-    };
-}
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requireWalletSubMatch = requireWalletSubMatch;
+exports.createScopeAuth = createScopeAuth;
+const token_v2_1 = require("../oauth/token-v2");
+/**
+ * 写操作钱包挑战（R2-1 设计 §4 + R2-2 预研方案 B）：写/高危操作必须叠加 walletAuth，
+ * 且签名者 === token 当事人（tv2=sub；第一方=用户地址）。token 丢了没有用户私钥
+ * 照样用不了写操作。
+ * 用法：router.post('/write-op', walletAuth(), requireScope('x:write'), requireWalletSubMatch(), handler)
+ * （walletAuth 在前，requireScope 在后。）
+ *
+ * 管辖范围（R2-2 方案 B，预研实现，待 kimi 拍板）：
+ * - tv2 token（tokenV2=true）→ 强制 walletAuth + signer===sub（R2-1 已有）
+ * - 第一方登录 token（isOAuth=false）→ 强制 walletAuth + signer===address
+ *   收口"隐式全权限"：第三方 App 即使拿到第一方 token 也做不了写操作。
+ *   不做 scope 检查——第一方默认 scopes 只有 profile/email，加检查会破坏
+ *   所有依赖第一方全权限的现有端点（orders/marketplace 等）。
+ * - v1 第三方 OAuth token（isOAuth=true 非 tv2）→ 保持豁免（本就有严格 scope 制）
+ */
+function requireWalletSubMatch() {
+    return (req, res, next) => {
+        const ou = req.oauthUser;
+        if (!ou)
+            return next();
+        // 豁免: v1 第三方 token (严格 scope 制已管), 不在本中间件管辖
+        if (ou.isOAuth && !ou.tokenV2)
+            return next();
+        if (!req.walletAddress) {
+            return res.status(401).json({
+                error: 'wallet-challenge-required',
+                message: ou.tokenV2 ? 'write op with tv2 token requires walletAuth headers' : 'write op with first-party token requires walletAuth headers',
+            });
+        }
+        if (req.walletAddress !== ou.address) {
+            return res.status(403).json({ error: 'wallet-sub-mismatch', message: 'signer must equal token subject' });
+        }
+        next();
+    };
+}
+function createScopeAuth(oauthPlugin, authPlugin, v2Deps) {
+    /**
+     * requireScope(scope) — 路由级中间件,校验 token 是否持有指定 scope。
+     *
+     * 第一方 token 隐式通过(用户自己 = 全权限)。
+     * 第三方 token 必须 scopes.includes(scope),否则 403 insufficient_scope。
+     */
+    return function requireScope(scope) {
+        return async (req, res, next) => {
+            const authHeader = req.headers.authorization;
+            if (!authHeader || !authHeader.startsWith('Bearer ')) {
+                return res.status(401).json({ error: 'missing_token', message: 'Authorization Bearer token required' });
+            }
+            const token = authHeader.substring(7);
+            // 0. tv2 结构化令牌 → 跨索引器离线验证（R2-1）
+            //    不查本地用户表（B 节点没有该用户行），sub 即身份。
+            if (token.startsWith(token_v2_1.TOKEN_V2_PREFIX)) {
+                if (!v2Deps) {
+                    return res.status(401).json({ error: 'token-v2-not-enabled' });
+                }
+                let issuerPubkey;
+                const parsed = (0, token_v2_1.parseTokenV2)(token);
+                if (!parsed) {
+                    return res.status(401).json({ error: 'invalid_token', message: 'malformed tv2 token' });
+                }
+                try {
+                    issuerPubkey = await v2Deps.issuerKeys.get(parsed.payload.iss);
+                }
+                catch {
+                    return res.status(503).json({ error: 'issuer-key-unavailable', message: 'chain query failed and no cached key' });
+                }
+                if (!issuerPubkey) {
+                    return res.status(401).json({ error: 'unknown-issuer' });
+                }
+                const verdict = await (0, token_v2_1.verifyTokenV2Offline)(token, issuerPubkey, v2Deps.revocations);
+                if (!verdict.ok) {
+                    return res.status(401).json({ error: 'invalid_token', reason: verdict.reason });
+                }
+                const p = verdict.payload;
+                if (!p.scopes.includes(scope)) {
+                    return res.status(403).json({ error: 'insufficient_scope', required: scope, granted: p.scopes });
+                }
+                req.oauthUser = {
+                    userId: p.sub,
+                    address: p.sub,
+                    scopes: p.scopes,
+                    isOAuth: true,
+                    clientId: p.client_id,
+                    tokenV2: true,
+                };
+                res.on('finish', () => {
+                    oauthPlugin.logAccess({
+                        appName: '', clientId: p.client_id,
+                        userId: p.sub, userAddress: p.sub,
+                        endpoint: req.path, method: req.method,
+                        scopeUsed: scope, responseStatus: res.statusCode,
+                    }).catch(() => { });
+                });
+                return next();
+            }
+            // 1. 先试第三方 OAuth token
+            const oauthInfo = await oauthPlugin.validateAccessToken(token);
+            if (oauthInfo) {
+                // 第三方 → 严格 scope 强制
+                if (!oauthInfo.scopes.includes(scope)) {
+                    return res.status(403).json({ error: 'insufficient_scope', required: scope, granted: oauthInfo.scopes });
+                }
+                // 解析 address
+                const user = await authPlugin.getUser(oauthInfo.userId);
+                if (!user) {
+                    return res.status(401).json({ error: 'invalid_token', message: 'User not found' });
+                }
+                req.oauthUser = {
+                    userId: oauthInfo.userId,
+                    address: user.address,
+                    scopes: oauthInfo.scopes,
+                    isOAuth: true,
+                    clientId: oauthInfo.clientId,
+                };
+                // 访问日志(PRD §27.9):仅第三方 OAuth token 记录,第一方不记
+                const appName = ''; // app_name 需要 JOIN 查,这里只记 endpoint/scope
+                res.on('finish', () => {
+                    oauthPlugin.logAccess({
+                        appName, clientId: oauthInfo.clientId,
+                        userId: oauthInfo.userId, userAddress: user.address,
+                        endpoint: req.path, method: req.method,
+                        scopeUsed: scope, responseStatus: res.statusCode,
+                    }).catch(() => { });
+                });
+                return next();
+            }
+            // 2. 后试第一方登录 token
+            const sessionInfo = await authPlugin.verifyToken(token);
+            if (sessionInfo) {
+                // 第一方 → 隐式全权限(用户自己的 session)
+                const user = await authPlugin.getUser(sessionInfo.userId);
+                if (!user) {
+                    return res.status(401).json({ error: 'invalid_token', message: 'User not found' });
+                }
+                req.oauthUser = {
+                    userId: sessionInfo.userId,
+                    address: user.address,
+                    scopes: sessionInfo.scopes,
+                    isOAuth: false,
+                };
+                return next();
+            }
+            // 3. 都不匹配 → 无效 token
+            return res.status(401).json({ error: 'invalid_token', message: 'Token not recognized or expired' });
+        };
+    };
+}
 //# sourceMappingURL=scope-auth.js.map

package/middleware/security.d.ts

@@ -1,48 +1,48 @@
-/**
- * Security Middleware - 安全中间件
- *
- * 功能：
- * 1. IP 白名单验证
- * 2. CORS 限制
- * 3. 请求日志审计
- * 4. 安全头部
- */
-import { Request, Response, NextFunction } from 'express';
-/**
- * IP 白名单中间件
- */
-export declare function ipWhitelist(allowedIPs: string[]): (req: Request, res: Response, next: NextFunction) => void | Response<any, Record<string, any>>;
-/**
- * 动态 CORS 配置
- */
-export declare function createCorsOptions(allowedOrigins: string[]): {
-    origin: (origin: string | undefined, callback: (err: Error | null, allow?: boolean) => void) => void;
-    credentials: boolean;
-    methods: string[];
-    allowedHeaders: string[];
-};
-/**
- * 审计日志中间件
- */
-export declare function auditLog(): (req: Request, res: Response, next: NextFunction) => void;
-/**
- * 安全头部中间件
- */
-export declare function securityHeaders(): (req: Request, res: Response, next: NextFunction) => void;
-/**
- * 请求体大小限制
- */
-export declare const requestSizeLimit: {
-    json: {
-        limit: string;
-    };
-    urlencoded: {
-        limit: string;
-        extended: boolean;
-    };
-};
-/**
- * 验证必需的环境变量
- */
-export declare function validateEnv(): void;
+/**
+ * Security Middleware - 安全中间件
+ *
+ * 功能：
+ * 1. IP 白名单验证
+ * 2. CORS 限制
+ * 3. 请求日志审计
+ * 4. 安全头部
+ */
+import { Request, Response, NextFunction } from 'express';
+/**
+ * IP 白名单中间件
+ */
+export declare function ipWhitelist(allowedIPs: string[]): (req: Request, res: Response, next: NextFunction) => void | Response<any, Record<string, any>>;
+/**
+ * 动态 CORS 配置
+ */
+export declare function createCorsOptions(allowedOrigins: string[]): {
+    origin: (origin: string | undefined, callback: (err: Error | null, allow?: boolean) => void) => void;
+    credentials: boolean;
+    methods: string[];
+    allowedHeaders: string[];
+};
+/**
+ * 审计日志中间件
+ */
+export declare function auditLog(): (req: Request, res: Response, next: NextFunction) => void;
+/**
+ * 安全头部中间件
+ */
+export declare function securityHeaders(): (req: Request, res: Response, next: NextFunction) => void;
+/**
+ * 请求体大小限制
+ */
+export declare const requestSizeLimit: {
+    json: {
+        limit: string;
+    };
+    urlencoded: {
+        limit: string;
+        extended: boolean;
+    };
+};
+/**
+ * 验证必需的环境变量
+ */
+export declare function validateEnv(): void;
 //# sourceMappingURL=security.d.ts.map