Skip to content
pkuinfoPublic

About

北大校园卡付款码安全共享 SPA · Go + Preact 单二进制 · 借出有度,刷卡安心

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

5 Commits

Folders and files

Repository files navigation

校园卡通行 · pkubdcard

北大校园卡付款码 · 安全共享 SPA

把你的校园卡借给同学一会儿,但不让出账号、不让出付款码原始链接、也不让任何中间人拿到密码。

Go Preact License: MIT


这是什么

借朋友刷一下校园卡付钱,是燕园里再常见不过的事。但常规做法——把账号密码直接告诉别人——既不优雅也不安全。

pkubdcard 把这件事做成了一个安全的小工具:

  • 分享方用校园网账号登录,生成一枚六位令牌,指定有效期,并可启用姓名验证(自选遮挡姓名中的哪些字);
  • 使用方只需输入六位令牌(必要时补全被遮挡的字),即刻拿到付款码,扫码付钱;
  • 全过程密码不出浏览器,付款码不落库,进程一关全部作废。

Note

这是一个个人/朋友间互助场景的小工具。请遵守《北京大学一卡通管理办法》及相关规定,对账号安全负责。

截图

主页(白) 主页(黑) 令牌已成
首屏聚焦"使用别人的卡","分享我的卡"作为次级入口 古风册页配色,北大红仅作主操作点睛色 六位令牌作为页面绝对主角

工作流

分享方 ──┐
         │  浏览器                                Go 服务
         ├─ 拉取 IAAA 公钥 ────────────────────────► /api/iaaa/pubkey ─► iaaa.pku.edu.cn
         │
         ├─ RSA-PKCS1v15 在本机加密密码 ────────────┐
         │                                         │
         ├─ 提交 {学号, 密文, OTP?} ─────────────────► /api/iaaa/login
         │                                         │
         │                          IAAA → portal2017 → berserker-auth → JWT
         │                                         │
         ├─ 收到 {jwt, name, account, ...} ◄────────┘
         │
         ├─ 配置 {TTL, 姓名验证遮挡位置} ────────────► /api/share ─► 6 位令牌
         │
         └─ 把令牌告知使用方


使用方 ──┐
         ├─ 输入令牌 ─────────────────────────────► /api/share/info ─► {需验证?, 王_明}
         ├─ (若需) 按顺序补全被遮挡的字
         ├─ 提交 ─────────────────────────────────► /api/use ─────► 付款码(会话随分享有效期存续)
         └─ 每 55s ───────────────────────────────► /api/use/refresh

安全设计

关注点 设计
密码 浏览器内用 IAAA 公钥做 RSA-PKCS1v15 加密;私钥只在 IAAA,诚实运行的服务端只见无法解密的密文。注意:下发加密 JS 与公钥的宿主若作恶仍可绕过——见下方「信任模型」
令牌暴破 6 位空间加 IP 速率限制(20 次/分钟)+ 单令牌 5 次失败锁定
用量语义 纯时间有效——令牌在 TTL 内始终有效、可反复领取;领取后建立的刷新会话与分享同寿,到期一并作废(不再有独立的短会话窗口,避免手机切后台后出现莫名的"已过期")
姓名验证 分享方逐字点选遮挡哪些字(可任意位置、可全遮挡),UI 实时打码预览 王•明;使用方看到 王_明 反向提示,按顺序补全被遮挡的字
JWT 有效期 TTL 自动 clamp 到 min(用户选择, JWT 24h 剩余)
持久化 全部内存登记,进程退出全部作废——这是 feature,符合"短生命周期"的设计目标

Important

信任模型(请如实理解)

浏览器用 IAAA 的公钥加密密码,私钥只在 iaaa.pku.edu.cn。因此一个诚实运行的本服务,转发时只看得到一段无法解密的密文(CORS 约束下浏览器无法直连 IAAA,密文确实要经本服务中转)。

但本服务同时下发了"加密用的 JS"和"公钥",所以一个恶意或被攻陷的部署完全可以掉包公钥、或篡改前端脚本来截获明文密码——客户端加密无法在密码学上防住作恶的宿主。真正的信任根是「谁在运行这个实例」+ HTTPS,而不是这层 RSA。

所以:本工具最适合自建、给信得过的人用;若要真正的零知识(可信代码在你本机运行、直连 IAAA),请用 pku-campuscard 这个 CLI。本网页版与它并不等价——代码由服务端下发,信任假设更弱。

快速开始

一键构建(产出单二进制)

git clone git@github.com:pkuinfo/pkubdcard.git
cd pkubdcard

# 1. 构建前端(产出会被 go:embed 嵌入二进制)
pnpm -C web install
pnpm -C web exec vite build

# 2. 构建后端
go build -o pkubdcard ./cmd/server

# 3. 运行
./pkubdcard -addr :8080

打开 http://localhost:8080。

开发模式

# 终端 A:后端(带请求日志)
go run ./cmd/server -addr :8080

# 终端 B:前端(Vite dev server,/api 自动代理到 :8080)
pnpm -C web exec vite

测试

go test ./internal/share/...        # 共享令牌注册/兑换/锁定/过期等单测
go vet ./...

项目结构

cmd/server/         入口;go:embed web/dist + Gin 路由 + SPA 静态回落
internal/iaaa/      PKU IAAA 公钥获取 + 密码登录(cookie jar)
internal/card/      portal2017 → berserker-auth JWT 交换 + 校园卡付款码 API
internal/share/     6 位令牌内存登记 + 接收方 session + GC + 锁定
internal/api/       Gin handlers + 单 IP 速率限制
web/                Preact + Vite SPA(构建到 web/dist 由 go:embed 嵌入)
  ├─ src/styles.css     设计系统 token + 组件样式
  ├─ src/App.tsx        模式选择 + 主题切换
  ├─ src/ShareFlow.tsx  分享方:登录 → 设置 → 令牌结果
  ├─ src/UseFlow.tsx    使用方:输入令牌 → 付款码 + 自动刷新
  ├─ src/theme.ts       三态主题(auto/light/dark) + localStorage
  └─ src/api.ts         JSON 接口封装 + ApiError

API 速览

方法 路径 用途
GET /api/iaaa/pubkey 透传 IAAA RSA 公钥
POST /api/iaaa/login {username, encrypted, otp?} → 全链路登录 → {jwt, name, account, payacc, paytype}
POST /api/share 注册一次共享,返回 6 位令牌
GET /api/share/info?token= 探测令牌是否需要姓名验证 + 打码姓名提示(如 王_明)
POST /api/use 兑取令牌 → {session_id, barcode, owner}
POST /api/use/refresh 刷新付款码(会话随分享有效期存续)

Tip

/api/use 与 /api/share/info 共用同一 IP 速率限制;爬过限制即返回 429。

设计系统

整个前端只用一组在 web/src/styles.css 顶部声明的 token:

  • 颜色——色板分 paper / paper-2 / paper-3、ink / ink-2 / ink-3、rule / rule-soft,加唯一红色 seal;明暗模式分别针对纸感与墨感校准对比度(ink ≥ 14:1)
  • 字体——Noto Serif SC(标题 + 数字"墨笔"效果)+ Noto Sans SC(正文)
  • 节奏——4px 间距阶梯,最大内容宽度 460px(专注感)
  • 动效——单一缓动 cubic-bezier(0.22, 1, 0.36, 1),prefers-reduced-motion 自动旁路

整体调性参考宋画册页与日式现代主义的留白:克制装饰,让六位令牌成为页面无可争议的主角。

上游致敬

本项目的核心鉴权链——

IAAA 密码登录 → portal2017 SSO → berserker-auth → synjones JWT → bdcard.pku.edu.cn 付款码 API

——直接移植自 pkuinfo/pkucli 中 pku-campuscard 这个 Rust crate。pkucli 用 CLI 把 IAAA、博雅空间、教学网、选课网等十多个系统整合在了一起,强烈推荐。

License

MIT

About

北大校园卡付款码安全共享 SPA · Go + Preact 单二进制 · 借出有度,刷卡安心

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages