進入票說明
作品開啟「接收進入票」後,玩家從碼舍小幫手的作品牆開啟作品時,網址後面會帶一張碼舍簽章的票。票裡只有這件作品專用的匿名玩家 id,你可以用它幫玩家存進度,不需要玩家另外註冊。
票在哪裡
票放在網址的 # 片段:https://你的作品網址/#mabao=<票>。如果作品網址本來就有 #(例如 https://example.com/#/level1),票會接在後面:#/level1&mabao=<票>。
# 後面的內容瀏覽器不會送到你的伺服器,也不會出現在 Referer,所以要用 JavaScript 從 location.hash 讀出來。
只有從小幫手開啟才有票。直接打網址、從書籤進來的訪客沒有票,你的作品要能當成沒登入的訪客處理。
在作品網頁讀出票
讀出後立刻用 history.replaceState 從網址列清掉,再送到你自己的伺服器驗證。不要把票放進查詢字串、記進紀錄檔,或送到第三方服務。
// 放在作品網頁的 <script type="module"> 裡,載入時執行:從網址的 # 片段讀出進入票
const match = /(?:^#|&)mabao=([^&]*)/.exec(location.hash)
const ticket = match ? decodeURIComponent(match[1]) : null
// 立刻從網址列清掉,免得玩家複製、分享網址時把票一起給別人;# 片段其他內容保留
if (match) {
const rest = location.hash
.replace(/(^#|&)mabao=[^&]*/, (_, prefix) => (prefix === '#' ? '#' : ''))
.replace(/^#&/, '#')
history.replaceState(null, '', location.pathname + location.search + (rest === '#' ? '' : rest))
}
// 送到你自己的伺服器驗章,換成你自己的登入狀態(只送自己的網域,不要送到第三方)
if (ticket) {
const response = await fetch('/api/mabao-login', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ ticket }),
})
// 成功後用你自己的 session 存取進度;失敗就當作沒登入的訪客
}
在你的伺服器驗證
票是 JWT(ES256 簽章)。網址上的東西誰都能改,一定要在伺服器驗過才相信。要檢查的項目:
- header 的
alg是ES256、typ是work-entry。 - 用商城公布的公鑰驗章:
https://shop.mashe.tw/api/works/entry-key。回應是 JWKS({ "keys": [...] }),用票 header 的kid找對應的那把。可以快取一小時;kid找不到時重新抓一次。 exp(到期時間,Unix 秒)還沒過。票簽發後 10 分鐘到期。work是你自己的作品 id,免得別件作品的票被拿來用。
驗過之後,用 sub 當玩家 id。內容只有 work、sub、iat(簽發時間)、exp 這幾項。
下面是 Cloudflare Workers 或 Node.js 20 以上可用的範例,只用內建的 WebCrypto,不用安裝套件:
const KEY_URL = 'https://shop.mashe.tw/api/works/entry-key'
const MY_WORK_ID = 'w_xxxxxxxxxxxx' // 你的作品 id,在「我的作品」頁看得到
// 商城的公鑰:快取一小時;票上的 kid 對不到時重新抓一次(商城換過金鑰)
let keys = null
let fetchedAt = 0
async function shopKey(kid) {
if (!keys || Date.now() - fetchedAt > 3600_000 || !keys.some(k => k.kid === kid)) {
const response = await fetch(KEY_URL)
if (!response.ok) return null
keys = (await response.json()).keys
fetchedAt = Date.now()
}
return keys.find(k => k.kid === kid) ?? null
}
function fromBase64Url(text) {
const binary = atob(text.replace(/-/g, '+').replace(/_/g, '/'))
return Uint8Array.from(binary, c => c.charCodeAt(0))
}
function decodeJson(part) {
return JSON.parse(new TextDecoder().decode(fromBase64Url(part)))
}
// 驗過回傳匿名玩家 id(sub),任何一項不對都回 null
export async function verifyEntryTicket(ticket) {
if (typeof ticket !== 'string' || ticket.length > 2048) return null
const parts = ticket.split('.')
if (parts.length !== 3) return null
let header, claims
try {
header = decodeJson(parts[0])
claims = decodeJson(parts[1])
} catch {
return null
}
// 1. 只收 ES256 + work-entry;碼舍其他用途的票 typ 不同
if (header.alg !== 'ES256' || header.typ !== 'work-entry') return null
// 2. 用商城公布的公鑰驗章
const jwk = await shopKey(header.kid)
if (!jwk) return null
const key = await crypto.subtle.importKey(
'jwk', { kty: jwk.kty, crv: jwk.crv, x: jwk.x, y: jwk.y },
{ name: 'ECDSA', namedCurve: 'P-256' }, false, ['verify'],
)
const ok = await crypto.subtle.verify(
{ name: 'ECDSA', hash: 'SHA-256' }, key,
fromBase64Url(parts[2]), new TextEncoder().encode(parts[0] + '.' + parts[1]),
)
if (!ok) return null
// 3. 沒過期(容許 60 秒時鐘誤差)
const now = Math.floor(Date.now() / 1000)
if (typeof claims.exp !== 'number' || claims.exp + 60 < now) return null
if (typeof claims.iat !== 'number' || claims.iat - 60 > now) return null
// 4. 是開你這件作品拿到的票,不是別件作品的
if (claims.work !== MY_WORK_ID) return null
if (typeof claims.sub !== 'string' || !claims.sub) return null
return claims.sub
}
注意事項
- 票只用來換你自己的登入狀態(例如 session cookie)。驗過後就換成你的 session,不要一直拿票當登入憑證;10 分鐘後票就失效。
- 拿到票的人在 10 分鐘內都能用它冒充那位玩家,所以作品網址要用 https,票不要記錄、不要轉給別人。
sub只在你這件作品固定:同一位玩家開別件作品會是另一個 id。你無法也不得試圖從sub反推玩家的碼舍帳號(見作品上架條款)。sub只代表「同一位碼舍玩家」,不包含名字、email 等個人資料。需要更多資料時請在作品裡另外徵求玩家同意。