从零到一：OCAP Playground 完全指南 - 掌握 DID Wallet 开发的声明式配置艺术

ocap-playground/
├── api/                    # 后端 API
│   ├── routes/            # 路由定义
│   │   └── auth/         # 认证处理器（60+ 个示例）
│   ├── libs/              # 核心库
│   │   └── auth.js       # 认证核心逻辑
│   └── functions/         # Express 应用配置
│       └── app.js         # 路由注册
├── src/                    # 前端代码
│   ├── pages/             # 页面组件
│   ├── components/        # UI 组件
│   └── libs/              # 前端工具库
└── tools/                 # 工具脚本

pnpm i @blocklet/cli -g

git clone git@github.com:blocklet/ocap-playground.git
cd ocap-playground

pnpm i

cp .env.bac .env
# 编辑 .env 文件，配置必要的环境变量

blocklet server init -f --mode debug
blocklet server start

blocklet dev

// ❌ 传统方式（命令式）
app.post('/api/auth/profile', async (req, res) => {
  // 1. 生成认证请求
  const authRequest = generateAuthRequest(...);
  // 2. 生成二维码
  const qrCode = generateQRCode(authRequest);
  // 3. 返回给前端
  res.json({ qrCode });
  // 4. 处理回调
  app.post('/api/auth/profile/callback', async (req, res) => {
    // 5. 验证凭证
    const isValid = await verifyCredentials(req.body);
    // 6. 处理业务逻辑
    await handleAuth(req.body);
  });
});

// ✅ 声明式配置
module.exports = {
  action: 'profile',
  claims: {
    profile: () => ({ fields: ['fullName', 'email'] })
  },
  onAuth: async ({ userDid }) => {
    // 只需关注业务逻辑
  }
};

onAuth: async ({
  req,              // Express 请求对象
  userDid,          // 用户 DID
  userPk,           // 用户公钥
  claims,           // 用户提供的所有声明
  challenge,        // 挑战值（防重放）
  extraParams,      // 额外参数
}) => {
  // 你的业务逻辑
}

// api/libs/auth.js
const walletHandlers = new WalletHandlers({
  authenticator: walletAuth,      // 认证器：处理 DID 钱包认证
  tokenStorage,                    // 存储：保存会话 token
  onConnect: args => {            // 连接回调
    // 用户连接时的处理
  }
});

// api/functions/app.js
walletHandlers.attach(
  Object.assign({ app: router }, require('../routes/auth/claim-profile'))
);

Object.assign({ app: router }, require('../routes/auth/claim-profile'))

{
  app: router,           // Express router（必需）
  action: 'profile',    // 动作名称（必需）
  claims: { ... },       // 声明配置（必需）
  onAuth: async () => {} // 回调函数（必需）
}

module.exports = {
  // 1. action：唯一标识符
  action: 'unique_action_name',
  
  // 2. claims：声明需要用户提供什么
  claims: {
    profile: () => ({ ... }),
    signature: async () => ({ ... }),
    // ...
  },
  
  // 3. onAuth：认证成功后的回调
  onAuth: async (params) => {
    // 业务逻辑
  }
};

claims: {
  profile: async ({ userDid, userPk, extraParams }) => {
    // 返回声明配置
    return {
      description: '请提供您的个人信息',
      fields: ['fullName', 'email']
    };
  }
}

onAuth: async ({
  req,              // Express 请求对象
  userDid,          // 用户 DID
  userPk,           // 用户公钥
  claims,           // 用户提供的声明数组
  challenge,        // 挑战值
  extraParams,      // 额外参数
}) => {
  // 处理业务逻辑
  // 可以返回数据给前端
  return { success: true };
}

module.exports = {
  action: 'profile',
  claims: {
    profile: () => ({
      description: 'Please provide your full profile',
      fields: ['fullName', 'email', 'phone', 'signature', 'avatar', 'birthday'],
    }),
  },

  onAuth: async ({ userDid, userPk }) => {
    logger.info('auth.onAuth', { userPk, userDid });
    // 这里可以保存用户信息到数据库
  },
};

<PlaygroundAction 
  action="profile"
  title="获取用户信息"
  buttonText="点击认证"
/>

module.exports = {
  action: 'claim_signature',
  claims: {
    signature: async ({ userDid, userPk, extraParams: { type } }) => {
      // 根据 type 参数生成不同的签名请求
      const params = {
        // 签名交易
        transaction: {
          type: 'fg:t:transaction',
          data: origin,  // 编码后的交易数据
        },
        
        // 签名文本
        text: {
          type: 'mime:text/plain',
          data: getRandomMessage(),
        },
        
        // 签名 HTML
        html: {
          type: 'mime:text/html',
          data: `<div>...</div>`,
        },
        
        // 签名摘要（用于大数据）
        digest: {
          digest: toBase58(hasher(data, 1)),
        },
      };
      
      return Object.assign(
        { description: `Please sign the ${type}` }, 
        params[type]
      );
    },
  },

  onAuth: async ({ req, userDid, userPk, claims }) => {
    const claim = claims.find(x => x.type === 'signature');
    
    // 验证签名
    if (claim.origin) {
      const isValid = await user.verify(claim.origin, claim.sig);
      if (!isValid) {
        throw new Error('签名验证失败');
      }
    }
    
    // 如果签名的是交易，可以发送到链上
    if (claim.meta && claim.meta.origin) {
      const tx = client.decodeTx(claim.meta.origin);
      const hash = await client.sendTransferV2Tx({
        tx,
        wallet: user,
        signature: claim.sig,
      });
      return { hash, tx: claim.meta.origin };
    }
  },
};

const { verifyPresentation } = require('@arcblock/vc');

module.exports = {
  action: 'test_vc_claim_filter',
  claims: {
    verifiableCredential: ({ extraParams: { type } }) => {
      // 旧语法：使用 item
      if (type === 'old-online') {
        return {
          description: 'Please provide your node Blocklet Purchase NFT',
          item: ['BlockletPurchaseCredential'],  // 旧语法
          trustedIssuers: [wallet.address],
          tag: blockletDid,
        };
      }

      // 新语法：使用 filters（推荐）
      if (type === 'new-online') {
        return {
          description: 'Please provide your node Blocklet Purchase NFT',
          filters: [  // 新语法：支持多个过滤器（OR 关系）
            {
              type: ['BlockletPurchaseCredential'],
              trustedIssuers: [wallet.address],
              tag: blockletDid,
            },
          ],
        };
      }

      // 多个过滤器：用户可以提供任意一个
      if (type === 'new-online-offline') {
        return {
          description: 'Please provide your Blocklet Purchase Credential and node Fake Passport',
          filters: [
            {
              type: ['BlockletPurchaseCredential'],
              trustedIssuers: [wallet.address],
              tag: blockletDid,
            },
            {
              type: ['PlaygroundFakePassport'],
              trustedIssuers: [wallet.address],
            },
          ],
        };
      }

      throw new Error(`Unknown type ${type}`);
    },
  },
  
  onAuth: async ({ claims, challenge }) => {
    // 1. 从 claims 中提取 VC presentation
    const presentation = JSON.parse(
      claims.find(x => x.type === 'verifiableCredential').presentation
    );
    
    // 2. 验证 challenge（防重放攻击）
    if (challenge !== presentation.challenge) {
      throw Error('Verifiable credential presentation does not have correct challenge');
    }
    
    // 3. 验证 VC 本身
    await verifyPresentation({
      presentation,
      trustedIssuers: [wallet.address],
      challenge
    });
  },
};

module.exports = {
  action: 'claim_asset',
  claims: {
    asset: async ({ userDid, extraParams: { type } }) => {
      // 传统方式：单一条件
      if (type === 'legacy') {
        return {
          description: 'Please provide asset and prove ownership',
          trustedParents: [factories.nftTest],  // 信任的父工厂
          trustedIssuers: [wallet.address],      // 信任的发行者
          tag: 'TestNFT',                        // 标签
        };
      }

      // 新方式：多个过滤器（OR 关系）
      if (type === 'either') {
        // 可以查询链上数据
        const { transactions: [tx] } = await client.listTransactions({
          accountFilter: { accounts: [userDid] },
          typeFilter: { types: ['create_asset'] },
          validityFilter: { validity: 'VALID' },
        });

        return {
          description: 'Please provide asset and prove ownership',
          filters: [
            // 过滤器 1：特定工厂和发行者
            {
              trustedParents: [factories.nftTest],
              trustedIssuers: [wallet.address],
              tag: 'TestNFT',
            },
            // 过滤器 2：特定标签
            {
              tag: 'NFTCreatedByMe',
            },
            // 过滤器 3：特定资产地址（如果用户创建过）
            tx ? { address: tx.tx.itxJson.address } : null,
          ].filter(Boolean),  // 移除 null
        };
      }

      throw new Error(`Unknown type ${type}`);
    },
  },

  onAuth: async ({ challenge, claims }) => {
    const claim = claims.find(x => x.type === 'asset');
    
    // 验证资产声明
    const assetState = await verifyAssetClaim({ claim, challenge });
    
    return { 
      successMessage: `You provided asset with tag: ${assetState.tags.join(',')}` 
    };
  },
};

module.exports = {
  action: 'claim_multiple',
  claims: {
    // 声明 1：用户信息
    profile: () => ({
      description: 'Please provide your profile',
      fields: ['fullName', 'email'],
    }),
    
    // 声明 2：签名
    signature: async ({ extraParams: { message } }) => ({
      description: 'Please sign to confirm',
      data: message,
    }),
  },

  onAuth: async ({ userDid, claims }) => {
    // 获取所有声明
    const profile = claims.find(x => x.type === 'profile');
    const signature = claims.find(x => x.type === 'signature');
    
    // 处理业务逻辑
    await saveUser({ userDid, profile, signature });
    
    return { success: true };
  },
};

claims: {
  asset: async ({ userDid, extraParams }) => {
    // 1. 查询链上数据
    const assets = await client.listAssets({ owner: userDid });
    
    // 2. 根据业务逻辑决定需要什么
    if (assets.length === 0) {
      return {
        description: 'You need to create an asset first',
        // 可以引导用户先创建资产
      };
    }
    
    // 3. 返回动态配置
    return {
      description: 'Please provide one of your assets',
      filters: assets.map(asset => ({
        address: asset.address
      }))
    };
  }
}

onAuth: async ({ claims }) => {
  const claim = claims.find(x => x.type === 'signature');
  
  if (!claim) {
    throw new Error('Missing signature claim');  // 会被捕获并返回
  }
  
  // 验证失败也抛出错误
  if (!await verify(claim)) {
    throw new Error('Verification failed');
  }
}

<PlaygroundAction 
  action="claim_signature"
  extraParams={{ 
    type: 'transaction',
    message: 'Hello World'
  }}
/>

claims: {
  signature: async ({ extraParams: { type, message } }) => {
    // 使用自定义参数
    return { data: message };
  }
}

onAuth: async ({ claims }) => {
  // 处理逻辑...
  
  return {
    successMessage: '操作成功',
    data: { userId: '123', token: 'abc' },
  };
}

// api/functions/app.js
walletHandlers.attach(
  Object.assign({ app: router }, require('../routes/auth/claim-profile'))
);
walletHandlers.attach(
  Object.assign({ app: router }, require('../routes/auth/claim-signature'))
);
// ...

// ✅ 好的命名
action: 'claim_profile'
action: 'claim_signature'
action: 'verify_vc'

// ❌ 不好的命名
action: 'claimProfile'      // 应该用下划线
action: 'CLAIM_PROFILE'     // 应该全小写
action: 'profile'           // 太简单，容易冲突

onAuth: async ({ claims, challenge }) => {
  const presentation = JSON.parse(claims[0].presentation);
  if (challenge !== presentation.challenge) {
    throw new Error('Invalid challenge');
  }
}

onAuth: async ({ userPk, claims }) => {
  const claim = claims.find(x => x.type === 'signature');
  const isValid = await user.verify(claim.data, claim.sig);
  if (!isValid) {
    throw new Error('Invalid signature');
  }
}

claims: {
  verifiableCredential: () => ({
    filters: [{
      trustedIssuers: [wallet.address],  // 只信任特定发行者
    }]
  })
}

claims: {
  asset: async ({ userDid }) => {
    // 异步查询，不阻塞
    const assets = await client.listAssets({ owner: userDid });
    return { filters: assets.map(...) };
  }
}

const cache = new Map();

claims: {
  asset: async ({ userDid }) => {
    if (cache.has(userDid)) {
      return cache.get(userDid);
    }
    const result = await queryAssets(userDid);
    cache.set(userDid, result);
    return result;
  }
}

claims: {
  profile: () => {
    console.log('Generating profile claim');
    return { fields: ['fullName'] };
  }
}

onAuth: async ({ userDid, claims }) => {
  console.log('User authenticated:', userDid);
  console.log('Claims received:', claims);
}

// api/routes/auth/my-feature.js
module.exports = {
  action: 'my_feature',
  claims: {
    profile: () => ({ fields: ['fullName'] })
  },
  onAuth: async ({ userDid }) => {
    // 业务逻辑
  }
};

walletHandlers.attach(
  Object.assign({ app: router }, require('../routes/auth/my-feature'))
);

<PlaygroundAction 
  action="my_feature"
  title="我的功能"
/>

claims: {
  verifiableCredential: async ({ userDid, extraParams: { level } }) => {
    if (level === 'basic') {
      return {
        filters: [{ type: ['BasicCredential'] }]
      };
    } else if (level === 'premium') {
      return {
        filters: [{ type: ['PremiumCredential'] }]
      };
    }
  }
}

claims: {
  profile: () => ({ fields: ['fullName'] }),
  signature: () => ({ data: 'Confirm' }),
  verifiableCredential: () => ({ filters: [...] })
}