Over the past 3 months, I’ve done the following:

• Added E2E testing running on Selenium
• Made most permissions optional
• Improved the stability of the Firefox version (mainly by reverting to Manifest V2)
• Added a feature to copy bookmarks in Firefox
• Added a feature to copy tab groups in Chrome
• Added a feature to copy HTML as Markdown
• Various code improvements (mainly switching to async/await)
• Used Bulma.css for styling

This post is also available in Chinese. 本文亦有中文版。

E2E Testing

As mentioned above, with minimal maintenance, it has few features, and relied on manual testing. When adding new features, I had to do cross-browser and cross-OS testing, which occasionally broke functions over the past 12 years. I primarily developed and tested on macOS and had never tested properly on Windows or Linux desktops. Recently, I got a second-hand PC, so I could test on Windows and Linux. But manual testing was still exhausting, so I researched E2E testing.

Ideally, E2E testing would directly trigger keyboard and mouse events. However, testing browser extensions isn't easy, especially when interacting with native UI elements like tabs, keyboard shortcuts, right-click menus, and permission prompts. Chrome's official guide lists tools like Selenium, WebDriver, and Puppeteer, but the documentation isn't comprehensive. I spent a lot of time exploring these tools and also considered Sikuli and Robot Framework, but they weren’t easy to use, so I didn’t try any of them. Tools like Puppeteer/WebDriver, based on the Chrome Developer Protocol, can only control the web page within the browser and can't interact with the OS's native UI, making them unsuitable.

In the end, I chose Selenium's Java version because it can call AWT's Robot library to send keyboard and mouse events to the OS. This decision proved correct because Java's cross-platform nature saved me a lot of trouble. Selenium and AWT are also well-established tools, making it easy to find Q&A and unusual tips & tricks. For example:

• Robot can only send events to the current application. When opening Selenium with TestNG, the focus is on the Test Runner, so it is necessary to use driver.switchTo().window(handle) to switch the window focus.
• Sending macOS combination keys with Robot requires a 200ms delay between modifier keys and non-modifiers; on Windows, you may need to call keyRelease() depending on the situation.
• When navigating the right-click menu, you can directly "type" with keyboard events, but it doesn't always work.
• In Selenium, only the Window is intractable, not the Tab, and certainly not Tab Groups. Therefore, I created an E2E Testing Support Extension to call Chrome's API to open test tabs.
• For optional permission prompts, in Firefox, you can directly set extensions.webextOptionalPermissionPrompts=false to disable the prompts. In Chrome, you only need to allow once, so I send keyboard events to allow all permissions at once before running test cases.

Running all tests takes about 3 minutes, which is acceptable but might be over-testing. There are still issues on Windows and Linux (KDE) that prevent all tests from passing. I'm considering moving some tests to Puppeteer, directly calling background.js event handlers, assuming the browser can correctly trigger keyboard and right-click menu events. However, this would require setting up another framework, so I'll postpone it for now.

During development, I used JetBrains Aqua and PasteNow to record clipboard content, which I highly recommend.

Optional Permissions

Copy as Markdown has had the export tabs feature from early versions, so it required the tabs permission. Recently, I added the tabGroups feature to export tab groups in Chrome and Edge. When the extension requests new permissions, Chrome shows a warning. Shortly after, users started complaining, "Why do you need to see my browsing history?" Many users also chose to uninstall (about 5%). This is because Chrome's permission warning displays "Read your browsing history," which technically isn't incorrect since accessing tab data means you can monitor browsing history. But this is alarming to general users, who might think the program is constantly monitoring them.

This churn rate was too damaging, so I started spending time changing permissions to avoid any warnings during installation. I moved all permissions that trigger warnings to optional, allowing users to decide whether to grant, and providing a feature to revoke permissions anytime, hoping to mitigate the churn.

Although my program is open-source, I can't expect all 10K weekly active users to read and understand the code before using it. As a practical PM, I have an obligation to improve this part of the UI. The lesson here is to give users the option to access sensitive information.

In the past 3 months, besides making the original tabs permission optional, I also made the new tabGroups and bookmarks permissions optional. The latter must be optional because the related feature only supports Firefox.

Firefox Version Reverts to Manifest V2 (Temporarily)

Manifest versions can be understood as API versions for browser extensions. The latest version is V3, which is nominally a spec driven by a W3C workgroup, but practically driven by Chrome's market dominance. MV3 is mandatory in Chrome, and MV2 is no longer accepted. However, for various reasons, Firefox currently supports both MV2 and MV3. The APIs are mostly similar, with small differences mainly being Promise, but those small differences require adding many if (typeof chrome.xyz === 'undefined') and callback-to-Promise wrappers, which is quite annoying.

Since Chrome is pushing MV3, Firefox is forced to follow. I initially assumed MV3 would unify everything and chose MV3 for Firefox considering code maintenance. However, this caused a mysterious right-click menu disappearing issue in Firefox. I tried several hacks but couldn't fix it, so I reverted to MV2.

This brings back the callback vs. Promise API issue. Initially, I thought I could manually wrap a few APIs, but it became increasingly cumbersome. So, I introduced Mozilla's webextension-polyfill.js, allowing most code to be written using async/await.

My long-term goal is still to migrate to MV3, but for now, I'll leave it as is since it works, and I have E2E tests to prevent breaking changes (hopefully).

Acknowledgements

This major update was possible thanks to my parental leave. First, I thank my daughter Rena for being born; this 3.0 version is named in her honor. Second, I thank the mother of the child, my wife Serena, who is also a full-time UI/UX designer, for providing valuable feedback during the UI design process. I also thank my company BONX Inc for allowing me to take parental leave. Our software development team is continuously hiring in Tokyo, Japan. Lastly, I thank the Japanese government for the parental leave allowance.

By the way, Copy as Markdown now has a donation link. Please feel free to donate!

(This post was translated from Chinese with assistance from Notion's ChatGPT Translator.)

過去三個月以來主要做了這些事情：

• 加入基於 Selenium 的 E2E 測試
• 將大部分權限改為選配
• 改善了 Firefox 版本的穩定度（主要是改回 Manifest V2）
• 在 Firefox 加上了複製書籤的功能
• 在 Chrome 加上了複製分頁群組的功能
• 加入HTML複製成Markdown的功能
• 一些程式改善（主要是改成 async/await）
• CSS套版，主要是 Bulma.css

本文亦有英文版。This post is also available in English

E2E 測試

如前所述，向來都是低度維護的情況下，功能很少，測試工具都是靠手動，一時要加上新功能，就要各種瀏覽器各種OS交叉測試，過去12年也不時會把功能改爛。以往都是在 macOS 開發測試，從來沒有在 Windows 和 Linux 桌面好好測試過；最近買了一台二手的 PC，至少有 Windows 和 Linux 可以測。但手動測還是很累，所以研究了 E2E 測試。

所謂 E2E 測試，理想上還是直接發鍵盤滑鼠事件，但實際上要測試瀏覽器擴充套件並不是那麼容易，尤其要與原生UI互動，這其中包括分頁、鍵盤快速鍵、滑鼠右鍵選單、權限警告等。Chrome 官方的指南並不是很齊全，只大略列出有哪些工具可以用，例如 Selenium、WebDriver、Puppeteer等，但各家的指南也不是很齊全，花了不少時間自己摸索，也曾經考慮 Sikuli 和 Robot Framework，但工具鏈不是很好上手，所以作罷。又如 Puppeteer / WebDriver 是基於 Chrome Developer Protocol 的，只能控制瀏覽器裡面的網頁，摸不到 OS 的 native UI，也不太適合。

最後選用了 Selenium 的 Java 版本，因為可以調用 AWT 的 Robot 函式庫來對 OS 送出鍵盤滑鼠事件。事實證明這是對的決定，因為 Java 的跨平台特性讓我少掉很多麻煩，Selenium 和 AWT 也都是歷史悠久的工具，要找問答和奇怪的 tips & tricks 並不難。例如：

• Robot 只能送事件到當前應用程式。用 TestNG 開 Selenium，焦點會在 Test Runner，要用 driver.switchTo().window(handle) 切換視窗焦點。
• 用 Robot 送出 macOS 的組合鍵需要在 modifier keys 和 non-modifiers 之間加入 200ms 的 delay；在 Windows 則需要視情況呼叫 keyRelease() 。
• 瀏覽右鍵選單的時候可以直接用鍵盤事件「打字」——但並非每次都會成功。
• 在 Selenium 裡面只看得到 Window，看不到 Tab，當然也看不到 Tab Groups，因此我另外做了一個 E2E Testing Support Extension 來調用 Chrome 的 API 開啟測試用分頁。
• 選配權限警告，在 Firefox 可以直接改 extensions.webextOptionalPermissionPrompts=false 關閉警告，在 Chrome 則只需要允許一次，所以就在跑測試前先用鍵盤事件全部允許。

全部跑完大約要3分鐘左右，其實還算可以接受，但有點覺得是不是過度測試，而且 Windows 和 Linux (KDE) 還是有些問題無法全部通過。正在想把一些測試改到 Puppeteer，直接呼叫 background.js 的 event handlers 就算數，畢竟我可以假設瀏覽器本身可以正確呼叫鍵盤和右鍵選單的事件。但那又要折騰另一套 framework，所以暫時作罷。

開發的過程中，用了 JetBrains Aqua，及 PasteNow 來紀錄剪貼簿內容，很方便，推薦。

選配權限

Copy as Markdown 在很初期就有匯出分頁的功能，所以有 tabs 權限。日前加上了 tabGroups 的功能，可以同時匯出Chrome和Edge的分頁群組。當擴充套件要求新的權限時，Chrome就會出現警告。不久後就有零星的用戶抱怨「為什麼要看我的瀏覽紀錄？」而且也有很多使用者選擇解除安裝（大約5%）。原來是 Chrome 的權限警告會顯示「讀取您的瀏覽紀錄」，其實就是存取分頁的 tabs 權限。技術上也沒錯，因為可以拿到分頁的資料就表示可以隨時監控你瀏覽了什麼網頁，但老實說這實在是太嚇唬人了，一般用戶會覺得這個程式會無時無刻監控。

我覺得這個churning實在太傷，所以開始花時間改權限，目標是安裝時不會出現任何權限警告，把所有會出現警告的都放在選配，讓使用者自行決定，也做了功能讓使用者隨時取消，希望可以藉此止血。

沒錯，我的程式是開放原始碼，但我不可能期待那10000週活用戶都先看得懂程式碼再來用。作為一個實質上的PM，當然有義務改善這部分的UI。這件事的教訓就是，要給使用者選擇是否可以存取敏感的資訊。

在過去三個月裡，除了原本的分頁 tabs 改成了選配，新功能分頁群組 tabGroups 和書籤 bookmarks 也改成了選配。後者必須是選配，因為相關功能只支援 Firefox。

Firefox 版回歸 Manifest V2（暫時）

Manifest 的版本可以簡單理解為瀏覽器擴充套件的 API 版本。現在的最新版是 V3，名義上是某 W3C 群組主導的規格，實務上是 Chrome 挾市場地位主導的。MV3 在 Chrome 已經變成必備，舊版 MV2 已經無法上架，但因為各種原因，Firefox 目前是 MV2 和 MV3 都同時支援。兩者之間的 API 大同小異，主要差異在 Promise，但那些小異已經讓我必須加入一大堆 if (typeof chrome.xyz === 'undefined') ，以及 callback-to-Promise wrapper，相當煩人。

由於 Chrome 力推 MV3，帶著 Firefox 被迫跟上。原本我也是抱持 MV3 會統一天下，加上程式碼的維護考量，所以在 Firefox 上了 MV3。豈料 Firefox 因此出現了神秘的右鍵選單消失問題，我試了好幾種 hack 都無法解決，最後還是退回了 MV2。

然而這就回到了 callback vs Promise API 的問題。本來是覺得只有幾個 API 就自己包，但愈寫愈覺得麻煩，於是就導入了 Mozilla 出的 webextension-polyfill.js ，至少現在大部分的程式都可以用 async/await 寫了。

長期目標還是想要改為 MV3，但現在能動就暫時放著吧，反正有 E2E 測試不怕改爛（？

鳴謝

這三個月有時間可以來做大改動，是來自育嬰假，首先感謝我的女兒 Rena 出生，這個 3.0 版是為了紀念她而跳的版號。第二是孩子的媽，我的太太 Serena，她同時也是全職 UI/UX 設計師，在 UI 設計的過程中給了我很多寶貴意見。此外也要感謝我的公司 BONX Inc 讓我休育嬰假，我們的軟體開發團隊長期在徵才（日本東京）。最後也要感謝日本政府的育嬰假津貼。

附帶一提，現在 Copy as Markdown 有贊助連結，如果想要贊助的話請隨緣～

提醒：簽證政策和申請規則可能會改變，本文寫在2024年，如果您在太久的未來看到這篇文章，有可能不再適用，請自行查證。

我跟太太都沒有日本國籍。因為小孩是在日本國外出生，視同外國人新規入國。原則上必須先取得定住者簽證才能在日本居住有身分。雖然網上可以找到有人先用免簽進日本再申請在留資格變更的記錄 (1) (2)，但考慮到就醫問題，所以不走這條路。

小孩的簽證類型，根據sponsor的身份不同而有所不同。我是永住者，帶親生孩子來日本居住，其簽證為「定住者」。前提是sponsor本人已經在日本居住（有住民票）。在日本國內出生的話可以參考這個網站。

順序：

1. 取得在留資格認定証明書（Certificate of Eligibility，以下簡稱CoE）
2. 用CoE申請簽證
3. 入境日本，在入境審查取得在留卡
4. 住民登錄

時程：

• 2024/03/06 送出CoE申請（線上）
• 2024/03/09 代理申請人離開日本
• 2024/04/30 寫信去要求提早審查（EMS國際郵件）
• 2024/05/10 CoE審查通過（Email收件）
• 2024/05/13 申請簽證（日本臺灣交流協會高雄事務所）
• 2024/05/16 簽證取件
• 2024/05/27 跟小孩一起入境日本
• 2024/05/28 住民登錄（役所）

取得CoE

2023年3月起，可以用マイナンバーカード線上申請家人的在留資格證明書，而且可以Email收件。線上申請需讀卡機（可以用臺灣賣的晶片讀卡機），需Windows。操作上很複雜，要有心理準備。辦帳號隔天才能生效，身份要選「法定代理人」。送出申請時代理人要在日本境內（Q4-17，而且系統會擋海外IP），但是送件後可以出國（Q4-18）。

申請分成兩個步驟：填表格、上傳資料。首先填完表格後，從登入後的頁面搜尋案件（在搜尋畫面什麼條件都不輸入就能全部列出），然後上傳照片和審查材料，再按下正式提交申請的按鈕。審查材料只能上傳一次，僅限一個PDF檔案，上限10MB，包含所有掃描檔，都必須在同一個檔案。可以用macOS的預覽程式編輯、壓縮。

關於線上申請填表的問題，入管有專線可以打去問。關於審查的問題，可以直接問永住審查部門。

雖然是線上申請，但所有文件都跟現場申請一樣，但不需附回郵信封。所需文件都在入管的官網上有公布：在留資格「定住者」（外国人（申請人）の方が「永住者」、「定住者」、「日本人の配偶者等」、「永住者の配偶者等」又は「特別永住者」のいずれかの方の扶養を受けて生活する、未成年で未婚の実子である場合）。

• 相片4x3cm電子檔：我們是請月子中心的合作攝影師幫忙拍（NT$1,000）。
• 扶養者の直近１年分の住民税の課税（又は非課税）証明書及び納税証明書：可以在役所申請
  • 所謂最近1年份，在6月以前只能拿到前年度的，在6月以後可以拿到去年度的。總之就申請最新的。不懂的話可以把入管官網的說明給役所的人看。
  • 我是3月申請的，所以只能拿到前年度的。為免入管跟我要去年的納稅證明，我還提供了去年的源泉徵收書和確定申告書（海外所得）。
• 扶養者の在職証明書：有沒有寫年收都沒差
• 身元保証書：列印簽名掃描
• 理由書（扶養を受けなければならないことを説明したもの、適宜の様式）：列印簽名掃描
• 申請人の本国（外国）の機関から発行された出生証明書：英文版出生證明（洽出生醫院），及日文翻譯
• 代理人與申請人的關係證明文件：英文版戶籍謄本（洽區公所），及日文翻譯
• 文件如果不是日文，必須附上日文翻譯。可以自己翻譯。在角落寫翻譯者姓名、聯絡電話和日期。
• 為保險起見，所有我自己寫文件，我都列印簽名再掃描。
• 不需要先辦護照就能申請，但需要附上理由書（參考），系統上的護照資訊是選填。但是外文姓名必須全部一致：英文版戶籍謄本=護照外文姓名=CoE申請表=在留卡。

3月初送件後，本來打算慢慢等3個月，但因為太太工作的緣故，需要6月以前入境。我在4月底打電話問受理的東京品川入管（永住審査部門），他們說現在案件很多，標準處理期間是3個月。可以寫理由書請他們加速，但不保證可以如願加速。而先用觀光簽入國再變更在留資格，不是不行，但審查要重來，耗費的時間差不多也是三個月。

抱著試試的心態，我在4月底寫了理由書，請入管提前審查（紙本，EMS從台灣寄到永住審查部門），寄達後2週即審核通過。

批下來的CoE只有電子郵件。上面有在留資格認定證明書的編號。很重要，別刪除。

辦簽證

要辦簽證必須有小孩的護照。

在日本台灣交流協會申請。有台北、高雄事務所，要去哪一間，原則上看戶籍地，但似乎可以跟交流協會要求在比較近的事務所辦理（未證實，請自行詢問）。我們戶籍在臺南，所以去高雄事務所，人很少。因為是嬰兒所以家長代理即可，本人不需到場。表格在交流協會的網站可以下載。

要帶的文件：

• 小孩護照：繳交正本及個人資料頁影本
  • 需簽名。家長代簽，再寫「母代/父代」即可。
  • 外交部領事事務局說家長代簽不會使護照失效。
• 簽證申請書：自行打字，列印，最下面簽名。所有欄位預設都是必填。
• 證件照 4.5 x 3.5 一張：規格同台灣護照
• 戶籍謄本中文版正本：用自然人憑證取得的PDF列印可
• 在留資格認定證明書：Email列印
• 委託書：家長代寫
• 代理人身分證：出示正本，繳交影本
• 出入國紀錄（移民署）：可以用小孩的健保卡申請PDF檔，列印出來
• 代理人在留卡：官網沒寫但是被要求出示

護照收走後，櫃檯會告知取件日期。我是過兩天可以去取件。

入境日本

取得簽證後就可以入境日本。在入境處需要提示CoE紙本或電子郵件；單憑簽證是不夠的。兒童的在留卡沒有照片。一家三口可以一起擠一個櫃檯。

還發現原來有在留資格的人，持再入國許可入境時不需要出示在留卡，他們只看（みなし）再入國許可。此外CoE申請時的上陸預定港有異動的話其實沒差。

順便抱怨：羽田T3入境審查的嚮導員也不知道我們該走哪個櫃檯。起先看我們有嬰兒推車，帶我們去優先櫃檯（嬰兒/身障用），結果說不能發在留卡，叫我們去隔壁日本人櫃檯，當然是被拒絕了。最後是帶我們插隊一般觀光客的櫃檯。關鍵句：「在留カードを作りたい。」

役所住民登錄

取得在留卡還是需要在居住地登記（住民登錄），才能有身份。這點所有在日外國人應該不陌生。

乳幼兒的話，家長代理去即可，小孩不需要出面。帶小孩的護照、台灣的英文版戶籍謄本、日文翻譯（收走）去辦。

マイナンバー本身會立刻發行，但是マイナンバーカード日後才會寄申請用明信片到家。

為了打預防接種，先申請了國民健康保險，當場拿健康保險證，之後再跟公司申請扶養家族健康保險證（手續可以詢問公司的人事部）。預防接種票需要去保健所申請。我帶了台灣的兒童手冊和英文版接種證明，讓保健所的人方便核對。或是自己告知他們需要打什麼疫苗（自我責任）。

整體來說覺得入管的規則寫得很詳細，雖然很複雜，但模凌兩可的地方很少，不愧是日本。線上申請可以省下往返入管的麻煩，電子收件也讓我可以回台灣照顧小孩，不用守在日本。但網站的設計真的很差，就好像是2000年代的企業內部資訊系統，幸好我是做Web開發的，大概可以摸索操作方式。其中最麻煩的是檔案只能上傳1次。

最酷的是因為是定住者的在留資格，所以沒有工作限制「就労制限なし」🤯

等待審核的時間是最痛苦的，只能說服自己先不要一直想，好好過日子。不過在留期間只有1年，不知道是不是因為我催促XD

那個外國的台灣代表處規定，台灣英文戶籍謄本上的名字就是該國護照上的官方姓名。又台灣的英文戶籍謄本遵循名從主人原則，只要拿得出證明（如出生證明、外國身分證件），就可以在戶籍謄本上寫這個名字，跟台灣護照加註外文姓名的原則一樣。戶政事務所的人員對英文姓名的寫法很有彈性，可以寫 「[台灣名音譯] a.k.a. [外文姓名]」 並列，也可以單寫「[外文姓名]」，總之只要能提出證明即可——畢竟是我們自己提出給外國機關，有錯我們自己負責。從父姓或母姓還是必須跟中文姓名一致。

在台灣剛出生的孩子還沒有出國，沒有外國的身分證件，所以唯一的方法是請醫院開英文版出生證明。我們孩子出生的醫院對於出生證明上的英文名字的寫法並沒有特別的規定，櫃檯人員聽到是雙重國籍就幫我們辦了。最後也順利在戶政事務所取得英文版戶籍謄本，寫的就是我們給孩子取的英文名字。

接著辦台灣護照，一樣是名從主人，如果非中文音譯必須提交證明，我們提交了醫院開的英文版出生證明和英文版戶籍謄本。在戶政事務所做人別確認的時候，戶所人員有把出生證明掃描上傳到外交部，並交代我們辦護照的時候要提交正本查驗。不過最後外交部是把英文版戶籍謄本收走了。

最終就得到了一本台灣護照上寫的是我們給孩子取的英文姓名，而不是中文音譯。

～～～

雖然還不知道這樣會不會對孩子未來造成混亂，但就我自己在日本生活（搞砸）的經驗，姓名還是一個用到底就好，不要耍帥節外生枝。

跟2010年比起來，現在的Linux桌面系統對使用者比較友好。不止外觀設計變了許多，也有各種新UX的嘗試，不再是單純仿製經典Windows的邏輯。CJK也有了思源黑體和思源宋體。筆電廠商對於Linux桌面的支援也好很多了，至少公司配的Lenovo ThinkPad有列在Ubuntu官方支持名單上，硬體驅動沒什麼問題。雖然後來知道NVIDIA顯卡驅動在Linux上還是有很多問題，但這臺是Intel內顯，也就少了個問題。

目前工作機是用Ubuntu LTS，主要還是爲了各種開發工具的相容性。印象中以前GNOME和KDE大同小異，選擇哪一套其實是基於個人審美。但某一版GNOME大改版，變得極簡風格，發明了新的視窗管理邏輯，聽說還有許多人因此跳到其他桌面系統，也有人fork了舊版的GNOME來維持經典操作邏輯。如今GNOME和KDE有明顯的不同，而非單純的審美差異。我用了一陣子Kubuntu，又換回了Ubuntu (GNOME)，還是看在大部分App只支援GNOME的網路效益。至於UI，也不是那麼難學，反而它借鑑了一些macOS的操作方式，很好上手。套一句雨傘店的廣告：顏色不好看，看久會習慣。

然而有些系統軟體還是很吃發行版和桌面環境。例如輸入法。過去的15年我都在用蘋果的繁體拼音輸入法，生活在日本需要日文輸入法，換到其他作業系統也是需要的。Linux有Rime的繁體拼音可以用，也有mozc的日文輸入法（據說是Google日文輸入法的開源版）。但輸入法畢竟是跟系統高度整合的程式，偶爾軟體更新會遇到問題。在fcitx5和ibus之間換來換去，哪個能用就用，反正都是同樣的Rime、同樣的mozc。之前用Windows內建的日文輸入法偶爾會壞掉，折騰了很久還是裝了Google日文輸入法。回想起來蘋果的多國語言輸入既穩定又包容[2]，輸入法這種東西就是平常用沒感覺，一旦壞掉就很令人煩躁。

又例如羅技鍵盤滑鼠。我用的是MX Keys Mini for Mac和MX Master 3，都沒有官方Linux支援，需要第三方軟體如Solaar，又因爲是系統軟體，在各發行版、Wayland的支援都不盡完美，也許那天軟體更新了就不能用。話說回來，MX Keys的Mac版不如一般版，後者還能切換Mac/Windows佈局，主要是交換Command（Meta/Win）和Option（Alt）的位置。Mac版不能在硬體上交換這兩個按鍵，對於肌肉記憶是一個很大的挑戰（但其實更大的問題是macOS的Emacs風格快速鍵，用Control移動遊標的那一組)。

總體來說，三個月用下來，Linux桌面給我的感覺是堪用、夠用。總是會有一些地方壞掉、當掉，需要在網上找答案，也許因此我對於各種完美的要求降低了。以前會很喜歡macOS應用程式所謂的原生界面設計，但離開macOS之後發現，Windows內建的App都沒有統一的，各種常用的生產力工具也都有自己的UI元件，尤其是Electron做的App，甚至字型渲染都沒有統一。如果我們都能用這些軟體來工作，那麼所謂「原生UI」似乎是個假議題：你可以選擇用原生SDK做一個App，但因爲一個App不夠原生就拒絕使用，豈不是把個人審美放在生產力之上，本末倒置。

[1]: 對，我嘗試過Windows WSL，但實在不喜歡折騰在兩個作業系統之間的不相容問題：換行字元、IDE相容問題、Docker、虛擬機橋接網路等。後來我認定直接在Linux上面開發Linux伺服器軟體，比在WSL簡單許多。

[2]: sort of 包容，至少macOS/iOS是唯一內建臺灣發音繁體漢語拼音的作業系統。字形輸入法如無蝦米就只能自求多福了。我也是因爲十年前iPhone不能打無蝦米也不習慣動態注音鍵盤，所以才學了漢語拼音，從那之後就再也離不開拼音。

對一些人來說，二十五到三十五歲不只是問卷調查上的一個年齡段選項，還是人生最充滿幹勁的精華時期。最幸運的那些人，沒有家庭的壓力，可以毫無後顧之憂地在事業中成長。我想我也是那群幸運的人之一。

而我就在日本度過了這個精華歲月。這個國家給了我永住權，還是百分之百是我自己努力來的，通過高度人才資格申請的永住。

事實上申請的過程中一直自我懷疑：真的這麼簡單嗎？Just like that? 這個國家認同我是「高度」人才嗎？明明放在台灣就是個普通的軟體工程師而已，普通大學本科畢業，沒有高學歷，收入也沒有特別高，幾乎就是壓線過關的。就因為過了最低標準，一般要等十年的永住申請門檻，我六年出頭就可以辦了。偶爾會參考其他西方國家的工作簽證，甚至台灣的就業金卡，雖然申請永久居留證的居住要求很短，但資格門檻要求很高，相較之下，日本真的對我這種普通人很友善。

但是拿到了就是拿到了，從此人們不會再問我簽證效期剩多久、有沒有回國的打算、拿工作簽裸辭會不會被遣返等等。就像當初勉強高中畢業、勉強大學畢業、勉強考到駕照、勉強考過日檢，過了就過了，人們只看那張證照。

＊＊＊

來日本之前是抱著一個自大的心態。那時候前一家公司倒閉不久，正在求職，但過程不是很順利。也不是台灣沒有機會，就是個自大而已，自以為值得更高的薪水，以當時我的能力是高攀的。再加上我是個北漂的台南孩子，在台北住了八年從來沒喜歡過，於是就有了離開台北的藉口：既然都要改變生活方式，那就出國吧。

因為學了一些日語，就抱著試試的心態去找了日本的人力仲介，用蹩腳的日語，找到了第一份工作。加上當時還是個動漫宅，對日本生活存有粉紅泡泡的幻想，於是就踏上了赴日之旅。

現在回想起來，移居日本大概是我人生中做過的決定之中，最值得的一個。

東京在一些方面比台北來得宜居。天氣不像台北那麼濕冷悶熱，衣服曬得乾。日本的租房市場比台灣成熟，雖然一定得透過仲介，但CP值是很穩定的。日本是行人的天堂，行人路權受到尊重，且人行空間很舒適；或應該說台灣對行人不友善是舉世聞名的。東京的大眾運輸以鐵路為首，四通八達，出行不需仰賴機車汽車 [1]。

這些剛好都是我很重視的生活條件，在台北找不到的，在東京找到了。

＊＊＊

在日本的生活也讓我得到了意想不到的收穫。

第一是英文能力。雖然英語不是東京的通用語，但在軟體業有一些公司只要求英語能力。文化上會更接近台灣人想像的美國外商，卻又不是外商。因為必須遵守日本勞動法，該有的社會福利都有，不像美國公司那樣把健保當福利，說解僱就解僱。而且不知何故，這些工作的起薪也比一般日企高，外國人當主管的也比比皆是，明明做的事情都差不多。

通英語的公司對英語的要求也通常不是那麼嚴格，畢竟大家都是從外國來日本討生活的，聽得懂就好，沒有人在管發音夠不夠道地。我就曾在一家充滿各國人的公司用英語上班，結果就是我在日本竟然把英語練起來了，還混了台美英澳星馬日口音。以前英文老師總是警告，口音不正胡言亂語，顯然在日本是不通用的；反而，只要講得出口，就有許多機會。

第二是下廚。台北大部分的單人套房不附廚房，日本就算是六坪的單人套房都有廚房。日本不像台灣有那麼多早餐店，外食也很貴，為了存錢不得不自己煮。剛來的時候，為了做三餐費盡了心思，從跟媽媽求救，到可以讀懂日本食譜；從張羅一餐兩小時，到現在俐落地每天準備一家兩口三餐。這是無數次的失敗累積來的。聽人家說台灣人一出國唸書就會變食神，至少我是學會了怎麼做台菜孝敬老婆。

第三是喜歡走路。由於對行人友善，我在東京養成了散步的習慣。最開始會去觀光景點，慢慢擴展到觀光景點附近的小徑小溪小山，最近兩三年會在住家附近的巷子到處漫步，或搭車去一個近郊車站，走幾公里到另一條鐵路的車站。以前連一個台北捷運600公尺的站距都懶得走，現在週末有空的話就會走個10公里。

最後是在東京遇見了人生的伴侶。雖然因為同為外國人，期間經歷了長久的遠距離關係，也因COVID而有長達一年無法見面，但最終我們還是在日本定居了。如果有小孩的話也可以靠我的永住權定居在日本，也少了一個煩惱。

現在想想，如果我沒移居日本的話，這些都不會出現在我的人生吧，至少不會是2023年。

＊＊＊

2468天。永住是一個淡淡的節點，除了在留卡換了一張，公所叫我去更新IC卡，其他似乎沒什麼改變；在台灣遞交結婚書約時的衝擊感還比較大，但也有 “just like that?” 的衝擊感。也許生活在法治國家的好處就是，公務員照章辦事，該給你的就給你，該是你的就是你的，蓋個章，發個文件，你就有了新的身分。Just like that。

而日子還是要過。

[1] 拿東京和台北的鐵路來比較其實很不公平。東京在20世紀初有郊外鐵路大拓荒時代，連結周邊衛星城鎮、名勝地或運輸砂石等資源。東京腹地大，城際鐵路途經之地當年多為農田，土地容易取得。現代的一出站就到家，多為都市擴張的結果，最初不見得是為了服務居民興建鐵路，更何況這些鐵路很多是私營的。台北先有都市化才有捷運，盆地造成腹地有限，無法形成廣域衛星城鎮，加上崇拜美國公路建設，城際鐵路沒有政治條件也沒有市場條件。台灣的都市若要以東京為目標發展鐵路，其實是要追趕一世紀份的進度。

I'll explain some backgrounds at the end, but I'd like to focus on how I did the merger because if you find this article, chances are that you have 10 reasons backing your decision to merge multiple Terraform templates, and want to prevent recreating the production resources; YMMV, but you find here.

All I can say is that it was an unpleasant journey.

At first, I thought it is as simple as:

• Copy-paste the existing code and put them into modules (folders)
• Pass variables from the root module to sub-modules
• Find all the resources from the old state file
• Figure out the address of the new resources (prefix the resource's address with module.${new_module_name})
• Run batch terraform import commands on all the resources
• Run terraform plan until Terraform is not planning to destroy or create any resources.

Code modification was easy. Listing all resources was not hard (although I created a script to extract them). However terraform import was not as easy as it seems.

A typical Terraform Import workflow is usually:

• Find the identifier of the resource
• Run terraform import to add the resource to the state file

Sounds easy? But it won't work for all types of resources.

Import is a feature that must be implemented in the provider itself. So these situations exist:

• The identifier depends on the implementation of the provider – it may not be obvious. It may be an AWS ARN, the resource's name displayed on the AWS Console, or some combination of its parameters. Please refer to the manual.
• Resources may support import command, but not all attributes will be imported, because not all attributes can be fetched from (AWS) API endpoints, e.g. passwords. In this case, Terraform may recreate the resource.
• Resources may not support import command at all. Terraform will think they don't exist and create new instances.

The ID Guessing Game

My approach is trial-and-error — assuming all resources can be imported with the id attribute in the Terraform State file, and if the Import command complains, check the documentation and find out what should be used as an ID. Most of them work. Just some exceptions. Some.

• The ID of aws_cloudwatch_log_stream is ${log_group_name}:${name}
• The ID of aws_iam_user_policy_attachment is ${username}/${policy_arn}
• The ID of aws_appautoscaling_target is ${service_namespace}/${resource_id}/${scalable_dimension}
• The ID of aws_ecs_task_definition is the ARN, obviously
• The ID of aws_security_group_rule is a combination of "security_group_id, type, protocol, from_port, to_port, and source(s)/destination(s) (e.g., cidr_block) separated by underscores _)." (cited from the official document)

Most resources I have encountered fall into some simple combinations of their attributes. The case of aws_security_group_rule is especially complicated. I assume there are some legacy compatibility issues, so I am not here to judge it. Just for your convenience, here is the JavaScript code I was using (not guaranteed to work for all combinations):

// attrs: the attributes property of that resources's instance from Terraform state
function aws_security_group_rule(attrs) {
    let source = "";
    if (attrs.cidr_blocks.length !== 0) {
        source = attrs.cidr_blocks.join('_');
    }  else if (attrs.source_security_group_id) {
        source = attrs.source_security_group_id;
    } else {
        console.error("CANNOT CONSTRUCT source OF aws_security_group_rule", attrs)
    }

    if (attrs.self === true) {
        source = `self_${source}`;
    }
    return `${attrs.security_group_id}_${attrs.type}_${attrs.protocol}_${attrs.from_port}_${attrs.to_port}_${source}`;
}

Secrets

Furthermore, I encountered some resources that are not possible to be imported by simply running terraform import:

• random_password
• random_string

As documented (links above), importing the result of the random-generated strings may still trigger re-creation on the next plan. The reason is that Terraform keeps a track of the random string's recipe (upper case, numbers, length, etc.) in the state file. import does not put those parameters into the state file when importing the value (because how do you know its recipe when you only have the dish, I mean, result?), therefore Terraform may think that the value does not match the recipe and try to recreate a new password, which invalidates the old password. To avoid this, refer to the documentation above, or just edit the state file and copy-paste the recipe (everything under attributes) from the old state file.

Other than the tainted value problem, you may also encounter political problems when importing random_password. As described above, to import a random value, you have to specify the random value's result to import, which is the actual secret password it generated, in the command line, that may stay in your shell history. This may sound like a security issue, but the fact that managing secrets in Terraform templates is already a security risk — the generated password is stored in the state file anyways, so anyone who can read the state file, i.e. anyone who can run Plan, can retrieve the password already — so, in reality, this is not more dangerous per see. But for your job security, check your company's security policy before doing this, whether or not it makes sense to you.

In addition to random values, if you have provisioned a tls_private_key in Terraform, you'll find it not possible to import, too. It is arguable whether or not creating a private key in the template is a good idea, but if the only thing you can do is import the state, in this case, the only solution is to copy-paste from the old state file.

False-Positive Drifts

Besides, some resources may trigger replacement because the Import was not implemented completely:

The master_password of an RDS instance cannot be imported. If this password is assigned by a random_password, make sure the random password won't be re-created (see above).

The secret value of aws_secretsmanager_secret_version might be marked as "need to change". In this case, if you are certain that the secret values won't change, likely, Terraform is just trying to mark the secret_string attribute as sensitive. The changes are internal only; they will not refresh the secret itself. To get rid of this, try manually editing the state file and modify to the sensitive_attributes array.

EC2 instances aws_instance may still trigger a replacement because Terraform believes network_interface should be recreated. I am not sure what condition triggers this behavior, but at least I workaround this issue by manually copying network_interface from the old state file over to the new one:

             "network_interface": [
+               {
+                 "delete_on_termination": false,
+                 "device_index": 0,
+                 "network_card_index": 0,
+                 "network_interface_id": "eni-XXXXXXXXXXXXXXXXX"
+               }
            ],

The Harmless Re-Creations

Some resources simply don't support terraform import, so when running terraform plan it will create new resources. But the only case I have encountered, aws_acm_certificate_validation , is harmless if they are recreated, so just let it run.

Other than the above resource ID issues, here are some tricks that helped me:

• Terraform 1.3.x will try to evaluate the whole template before importing the resources. This slows down the process, and sometimes Terraform refuses to run when there are hidden dependencies (dynamic for_each being one example). I was using Terraform 1.2.9 to avoid this problem.
• Running terraform import requires a -var-file. If you are using Terraform Cloud, just specify a file that has nothing in it.
• Editing Terraform state file might be helpful if you don't want to deal with unwanted changes on the next Plan. It's simple: terraform state pull > state.json, edit it, increase serial in the root, then terraform state push state.json.
• terraform import also requires read access to the resources that you want to import into the state. So for example, if the template uses some cross-account AWS credentials or providers from other cloud services, you'll want those credentials to be ready in your shell before running.

How Did We End Up Here

Prior to this merger, our templates were organized by microservices. There is a 'base' template for the resources that all the microservices depend on (e.g. network), then for each microservice, we have a template, that reads terraform_remote_state created by the base template, then builds its resources on top of them.

At first, we thought it will be a dependency tree, that there will be no circular dependencies. It late became clear that there are hidden dependencies managed outside Terraform's control, but back in the beginning we thought the dependencies can be easily found by reading the code, and we were able to manage them: a microservice A that wants to use resources from microservice B, and B may require resources created by A. Before we can refactor the template and create a dependency C that both A and B depend on, we must rollout to production, and proceed to another project. Cross-workspace references of terraform_remote_state can easily end up with mutual dependencies that we cannot manage easily, and at some point, we have to write a long operation guide, describing the dependencies of each microservices, and a step-by-step deployment guide to provision everything.

In short, starting with multiple Terraform templates is a premature optimization.

If you are about to adopt Terraform into your infrastructure management, and you are not sure whether to create one template or many, read the Terraform Recommended Practices, and put all things together as possible as you can, until you hit the border of the organization's structure (e.g. you have a DNS that is not managed by your team). Someday down the road, you'll find a necessity to split the mono-repo template into multiple ones, and by that time, you'll have a better idea of what should be separated. Probably you'll have an SRE team supporting you at that time. Avoid premature optimization at all costs.

Finally, this is not to say that Terraform isn't perfect and should be avoided. No tool is perfect. The benefits that Terraform brings to our team have exceeded the overheads that comes with it. Personally, I prefer Terraform (and similar declarative, type-checked Infra-as-Code tools) to e.g. AWS CDK. For the foreseeable future, I believe this will still be an important part of my work.

2022年心態上最大改變是不再堅持細節了。日語常說人有「こだわり」(Kodawari)，可以形容一個職人對自己的工藝有堅持，也可以形容任何人對枝微末節過度拘泥。我以前該算後者吧，很多事情明明非我所及也堅持到底。今年在工作和生活都嘗試著不再計較細節，怎麼方便怎麼來，怎麼順眼怎麼來，學習睜一隻眼閉一隻眼，學習放過自己，學習接受現實。人生變得比較自在。

工作

還在新創打拼。日本的新創從來不像矽谷那樣充滿幹勁和冒險精神，但累應該都是一樣累。當基層也不是那麼輕鬆，福利也是基本款。偶爾有一些高薪福利佳還發股權的也是屈指可數，並非常態。但也因為公司小，所以有很多討論空間，也不太有傳統日商的規訓，所謂規矩都不是聖經，都是可以商量的。最近我們組也多了許多外國人，雖然大家日語都很溜，但文件都寫英文了，偶爾也能用英語跟同事戰技術，在日本不必被苛求日語能力，還能練兩種外語，也算是一種小確幸吧。

有時候會懷念之前在大公司的日子，既不用擔心工作 (work) 哪裡來，也不用擔心錢，福利又好。現在想想，大概是還存著最後一絲少年心，想要拼一把的心情吧。說好聽一點是有挑戰精神，說難聽一點就是坐不住、定不下來。在這個歲數，也許是該收心了吧。以前前輩在說要安穩我都不信，現在我是真的懂了。

偶爾會想自己是不是拿的工資不夠資格，但到了年底，左耳聽說誰家裁員，右耳聽說誰家招人開的預算只有我工資的六成，就想說既然還存得了錢，手頭變緊了也還算緩衝範圍內，沒被公司共體時艱就感恩了。

專業

儘管新創比較累、風險比較高，但挑戰比較多、成長速度比較快。2022年我的科技樹都點在 Terraform、AWS 和 Go/gRPC。有厲害的同事帶路，學起來也特別快，概念一點就通的那種。

Terraform 比 CloudFormation 好的地方在於有自己的程式語言，後者 YAML 寫久了都在 debug YAML 本身。Terraform 和 CFN 都是 declarative 的，你寫的是成品最後的形狀，而不是裝機過程的腳本。AWS CDK 跟普通的腳本式裝機沒什麼兩樣，只是你可以選擇自己喜歡的程式語言，通常這就代表不同組用不同語言的混亂，再乘上各種語言的眉眉角角。而且最後還是生成 CFN template，為了部署 CDK 還要先部署一堆基建，又 vendor lock-in，何必呢？總之 Infra-as-Code 我現在還是比較看好 Terraform 的。

再說 AWS 吧，我廠主要還是用 AWS，但因為一些業務需求，有研究一下 Google Cloud 和 Azure，最後覺得要跑伺服器的話，還是 AWS 比較成熟，其他家都是追著 AWS 的車尾燈在跑。誠然 AWS 也是有許多細節不是那麼完美，但光考慮穩定度和靈活度，AWS 還是我心裡的雲端第一選擇。2022 年練了許多 ECS 的功，還把一套在 ElasticBeanstalk 跑的 API service 搬到 ECS 了，當然全部是用 Terraform 設計的。大概可以自信地說自己是系統架構師了吧。

再說 Go 跟 gRPC 吧。這大概是我這一年最成功的轉換跑道。2020 年我還在 Ruby on Rails 的世界裡打滾，遇到的各種挫折都覺得這不就是後端工程師的人生嗎？亂糟糟但是可以賺錢啊，公司先活下去再求好啊，it pays my bills 啊。後來研究了 Go 一陣子，才發現他們的世界並不像 Ruby 那麼亂七八糟，而是有條有理的，開發速度也快，新創也愛用，速度也快。有 static typing 就先避開了一大堆的問題。Go 寫起來行雲流水，GoLand 就像是手把手在幫我寫程式，頓時懷疑為什麼 Ruby 要把編程搞得這麼痛苦。以前討厭 IDE 單純是基於 RubyMine 太肥太慢，這還得歸咎於 Ruby 本身沒有 type checking，巧婦難為無米之炊。現在 Ruby 3 才在慢慢追上，工具鏈還像是紙糊的。總之，Go 是我相見恨晚的程式語言，原來寫程式可以這麼愉快。接下來幾年大概都要託他照顧了吧。

OAuth 2 繼續在我的工作中陰魂不散，今年認真學習了 PKCE 的流程以及 SAML 2.0，仔細拆開來看哪裡可以駭。偶爾讀一些 security breach 的新聞，也體會到這世界上沒有完美的系統安全，只有風險控管。

理財

如果我要選個年度 Emoji 的話大概是「💰」，因為 2022 年的日本經濟像雲霄飛車：日圓貶值、通膨沖天、央行升息，造成我沒幾天就有想要讀懂經濟新聞的焦慮，有時候還會後悔大學時沒跟同學去上總體經濟學的通識。這些新聞沒幾天就會出現一次，又在考慮買房子所以學了房貸101。我覺得這一年都在惡補經濟學的基本知識。

手頭既然還有餘裕就很想要投資，畢竟日圓放一天就會變薄，最近是變得特別薄（關鍵字：消費者物価指数 (CPI)），至少也得抗一下通膨吧。這是很有實感的，兩年來換了3次工作，工資沒漲多少，但手頭變緊了。以前在台灣工作的時候，存錢就是為了去日本玩，其他就是月光了，沒閒錢投資，就算有也是亂買一通，最近重新看了一遍 portfolio 才發現風險相當高。最近日本政府出台新的 NISA 免稅投資制度，接下來應該會認真用它了。這又是另一個前輩們耳提面命我卻當耳邊風的東西。也不知道算不算 FOMO 焦慮，就是每年都在後悔去年沒投資的那種。

但說到底，開源還不如節流來得有效。受到某些 Minimalism 極端派的影響，覺得信用卡是一種借錢花錢、所有的現金回饋都是消費主義，所以 2020 年以來就慢慢減少信用卡的使用，能用 Debit 卡就用，但又擔心 Debit 被盜刷整個戶頭被清空。現在在用的是 Kyash，這其實算儲值卡，可以跟銀行綁定自動加值、Visa 實體卡可以感應刷卡。COVID 之後「無現金社會」成為日本消費經濟的關鍵字，QR 掃碼支付的普及度在這兩年提升很多，但我還是懶得用掃碼，能刷卡就刷卡，留個 Line Pay 備用來刷 PayPay 條碼和 Apple Pay 感應。儲值卡的消費紀錄跟 Debit 一樣即時反應，每個月對帳比較輕鬆（信用卡有隱形的未請款消費額度），比較容易把握收支。缺點是現在要管理兩張儲值卡。要是 Kyash 可以支援 Apple Pay Visa 就好了。

閱聽

Podcasts 依然是我生活中很重要的資訊來源。2022 年很滿意且 2023 年會繼續追的 Podcast 節目如下：

• 跟錢有關：Planet Money、The Indicator by Planet Money、The New Bazaar、More or Less: Behind the Stats
• 滿足好奇心：99% Invisible、Twenty Thousand Hertz、日知录、生活漫游指南、天书广播 （歷史研究）、Short Wave （科普）、Lingthusiasm （語言學）
• 時事深度探討：声东击西、The Pulse from WHYY
• 哲學：迟早更新、不可理论、Casticle
• 軟體工程：牛油果烤面包、The Changelog
• 其他：故事 FM （人間異語）

今年又重新拾起 RSS 閱讀的習慣。故事應該跟許多人一樣：受不了社群媒體的演算法推薦，想要捏一套自己的口味。上次大量使用 RSS 大概是 2013? 的時候了。這次除了重新找回一些台灣軟體工程師的 blog，也開始嘗試閱讀英文長文。此外 YouTube 其實還保留了 RSS 功能，從 Feed Reader 訂的話，可以略過首頁的推薦區。最近有訂閱的是 CPG Grey、Veritasium 和 Vox。閱讀器用的是 NetNewsWire 搭配 FeedBin 雲端同步。

新聞閱讀則是儘量避免看台灣的新聞網站，太亂了。因為住在日本，主要還是上《Yahoo! ニュース》讀新聞，中文新聞主要看《BBC中文網》。科技新聞則首先看《The Verge》，但英文閱讀還是太慢，所以很仰賴他們的影音評測。《報導者》有感興趣的主題會偶爾看一下。

娛樂

該放鬆的時候完全不想看到日文和英文，而且2022年一直在尋找中文的環境，所以重新開通了 Spotify 台灣帳號。今年的洗腦專輯是《自本》和《ponso no Tao》（我聽不懂達悟語，只覺得旋律很魔幻）。

Apple TV+ 和 Netflix 都有訂，這兩家是日本少數提供中文字幕的串流。主要看美國和韓國番劇：

• 改變了世界觀：創造安娜 Inventing Anna, 白金業務員 White Gold, 黑錢勝地 Ozark, 小女子 Little Women (All Netflix)
• 改變了人生觀：愛情不設限 Love & Anarchy, 好萊塢 Hollywood, 碎片人生 Pieces of Her, 非常律師禹英禑, 我們的藍調時光, 塔盧拉 Tallulah, 阿穆的生存之道 Mo, 馬男波傑克 BoJack Horseman (以上 Netflix),  Swan Song, Pachinko, The Morning Show (以上 Apple TV+)
• 燒腦爽片：Severence, For All Mankind (以上 Apple TV+), 冒牌帝國 Fakes, 毒梟聖徒 Narcos-Saints, 下流正義 The Lincoln Lawyer, 籠中鳥 Inside Man (以上 Netflix)

值得一提的是看了《悲慘世界》2012年電影版，整整lag十年！小時候看過1995年演唱會版，所以腦子裡一直跟那個版本比較。那時候中二年紀小不懂事，連劇情都看不懂，老師帶著全班看，我也不懂他在淚推個什麼意思。看了電影版總算是把劇情補上了，才懂這部音樂劇要有點社會經驗才能懂。但總覺得演唱會版本整體上的演唱比較棒，電影版的除了安海瑟薇演的芳婷唱得很有張力，其他的就像在趕進度似的。也注意到主教面熟面熟，一查才知道是1995的尚萬強跑來演主教。我想是一種救贖吧。

漫遊

自從 Covid-19 以來我就漸漸養成了散步的習慣，從以前公館-台電大樓都嫌遠，到現在10公里算普通，也是自己的一大改變。東京走起來比台灣舒服，來東京玩過的人應該都知道。可以說2020年是散步元年、到了2021年，即時不看手機地圖也不太會在東京迷路了。

今年的走透透主要是為了在東京買房子，至少要知道哪裡好住哪裡很亂。實際造訪也不是不行，畢竟喜歡走路，也算是探險。但是東京太大了，總不能全部走透透再說要住哪。所以讀了不少東京地理大觀的雜書，大多是日本常見的捏他集，網路上偶爾也會有人整理的那種，不值一提。不過藉此重新發現我對地圖很有興趣，所以讀了今尾恵介的地圖識讀系列：《地図帳の深読み》、《地図帳の深読み 100年の変遷》、《地図鉄のすすめ》、《地図帳の深読み 鉄道編》。每個篇章都可以學到新知識，對於閱讀地圖也更有感覺，好比說路的輪廓可以說明哪裡有陡坡、路的形狀可以說明開發的年代、鐵路繞大彎通常是蒸汽火車爬不上去等等。漫遊在東京多了一層樂趣。

其實也許我對歷史的興趣完全是地圖宅的那種興趣也說不定。

攝影

邊散步邊拍照是最近兩年的興趣。為了便攜，今年從 Canon EOS Kiss X10 (Rebel SL3) 換到了 Fujifilm X-S10，試了好幾顆定焦鏡，現在比較喜歡 35mm 畫角（約全片幅的 50mm）。我很喜歡拍青苔，但一般的定焦鏡對焦距離太遠，應該是需要微焦鏡的，不過 Fujifilm X 系統的微焦鏡選項不是很多，最近出的是 30mm，感覺跟現在的鏡頭有點重複，還在觀望。

重新註冊了 Flickr，偶爾會發一些照片。不過最常發圖的地方還是在 Instagram 就是了。

其他

再度嘗試寫 Blog。自從 2019 年從 Medium 搬家到 Static-Site Generator 之後，就非常沒有寫文章的動力，主要還是覺得寫個文章像在跟 Markdown 編譯器吵架似的，跑得快的編輯器很陽春，功能足的編輯器又慢又像在寫軟體。且 Git 發稿流程太儀式化了，像在發布軟體新版一樣，改個錯字還得 git commit git push git merge。現在用 Ghost 兜了一套 headless CMS，前端依然用 SSG，但後台管理就舒舒服服的，按發布就發布，按存檔就存檔。Ghost 編輯器我用得很開心，要連結有連結，要插圖有插圖，Markdown 拋在腦後了。寫得出這篇文章也是靠 Ghost 後台的。我知道有很多人喜歡純 Git 流程，但我還是比較喜歡 GUI。

電腦軟體全部換成了中文版。以前堅持用原文版，一直覺得電腦軟體的中文翻譯參差不齊，不完美的東西看了就扎眼不如不看，反正看得懂英文和日文。最近覺得還是中文看得順眼，看到英文和日文就想到工作，所以能換繁體中文版的都換了，翻譯品質就算了，不想計較。缺點是在日本開 Google Maps 偶爾會看到奇怪的中文翻譯。

改用 Firefox。不是為了什麼反隱私的意識形態。一開始是工作中要操作多個 AWS 帳號，發現 Multi-Account Containers 很好用。漸漸發現 Firefox 整體都好用，古時候瀏覽器常見的那些微調設定，在 Chromium 被拔掉的那些，Firefox 都還留著，有種新潮的懷舊感。字體我也不再那麼挑剔了，能看就好，我又不是搞設計專業的。

以及開始在 Mastodon 活動了，在 Twitter 開始被蹂躪的時候註冊了帳號，現在看來還是小圈圈比較適合我，也沒有社交關注度的壓力。歡迎關注： @yorkxin@g0v.social。

那麼2022年就這樣吧。還算是有收穫的一年。

原本用的是 Microsoft Sculpt Ergonomic Keyboard，這把是人體工學設計，左右按鍵區域的中間有個分隔，花了一些時間習慣以後，打起來很舒服，手腕和肩膀的酸痛有比較緩和。當初為了美式佈局還從美國進了水貨到日本。但是因為開始用 JetBrains IDE 工作，它有很多快速鍵是安排在 F 功能鍵，這把鍵盤的 F 區非常難按，像是年久失修的卡帶錄音機。所以開始物色市場上的鍵盤。

首要條件是美式佈局，這在日本的公司貨就選項很少了。第二條件是無線，且得支援多設備連線，因為公司的電腦和私人的電腦都要用。微軟那支本來就只有 2.4GHz USB，Dell U2720Q 可以插在螢幕的 USB 上，透過 USB-C 連到筆電，所以不是問題；市場上的商品大部分是藍芽的，選項不多。第三是不要機械鍵盤，最好是筆電觸感的，鍵程短的，這是我個人喜好。最好沒有數字鍵區。本來還很堅持一定要有編輯鍵，但是看在市場上有的選項真的不太多，只好放棄。基本上我的完美鍵盤是 Logi MX Mechanical Mini 的佈局、Apple Magic Keyboard 鍵盤的觸感。

最後還是選了 Logi MX Keys Mini，而且日本公司貨得要 Mac 版的才有美式佈局。

打字觸感很滿意，比 Apple 的 Magic Keyboard 外接鍵盤再那麼好一點。F 功能鍵也比 MacBook Air (2020) 和微軟那把鍵盤的大很多，好按很多，有種一等公民的感覺。多設備切換我嘗試了藍芽和 Logi Bolt USB 接收器（選購），最後還是懶得切來切去，直接用 USB 了。可惜手邊的 MX Master 3 不能用這顆接收器，且內附的 USB 接收器訊號插在螢幕後面就不如藍芽穩定，不然就真的實現 USB-C 熱插拔 KVM Switch 了。

不過初期還是發現一些挑剔的點，用了才知道的：

第一是媒體鍵區的客製選項很有限。媒體鍵跟 F 功能鍵是一起的，透過 Fn 組合鍵來發動，或是 Fn+Esc 來鎖定。Logi Options+ 工具程式裡面可以選的選項不多，而且Fn+🔊大聲 這個組合是無法單獨設定，例如設定了🔊大聲鍵為 Page Down，那麼按了 Fn+🔊大聲 也依然是 Page Down。

第二是想要設定 CapsLock = Ctrl 得透過 Karabiner Elements，macOS 的鍵盤設定無效。發現這件事當下還想上拍賣網站放手了，因為我很習慣 Ctrl 在 A 左邊這個位置（可以參考2016年的拙文）。不過跟微軟那把鍵盤筆記起來，至少 MX Mini 有大寫鎖定燈了。

第三是左 Ctrl 不能指定到別的按鍵。我設定成 CapsLock 發現按了Fn + 🌛 = 鎖屏，竟然會離開應用程式。用 Karabiner Elements 看了鍵盤事件，才發現這把鍵盤的 Fn + 🌛 = 鎖屏功能，實際上是送出 [左 Ctrl] + Cmd + Q 的組合鍵，也就是 macOS 預設的鎖屏快速鍵。所以如果把左 Ctrl 設定成 CapsLock，那麼就會觸發 Cmd + Q = 離開應用程式。當然另一個明顯的解法是把鎖屏快速鍵改成別的，但考慮到我也很少按 CapsLock，就算了。現在我有兩個 Ctrl 呢。

其實沒有編輯區還是不太習慣，現在是把🔊大聲設定成 Page Up，把🌛設定成 Page Down（預設是切換勿擾模式），但還是很懷念 Home 和 End。再考慮要犧牲哪個按鍵好了。

至於文首說的肌肉痠痛問題，可能是無解了，只能認老吧。Logi 有出人體工學鍵盤，但是數字鍵還是太佔空間了。

最後還是想抱怨一下日本市場對美式鍵盤真的很不友善，美式鍵盤幾乎僅限於高級機械鍵盤，筆電除了 Dell XPS、Lenovo E 系列和 Apple 全系列之外，幾乎都只有日文鍵盤，想要美式鍵盤還得進水貨，又說無保固，又說沒有總務省的電波檢驗。

有興趣的可以參考〈Logitech MX Keys Mini Review - RTINGS.com〉這篇評測。

以下是我一直以來的猜想：

1. 我訂閱的節目在最近兩三個月變得很多，但是真正去聽的很少，所以有些該退訂。
2. 我聽節目的喜好程度是中國普通話節目 > 台灣國語節目 > 台語節目 > 英語 >> 日語。
3. 一開始都是聽中國的節目，而從某一段期間開始狂聽英語節目。
4. 開始在家工作之後似乎聽的時間變多了，儘管沒有通勤。

於是我好奇我的行為有沒有什麼改變。

尤其是「訂了沒在聽」的問題，一直困擾著我。我有公開一個我訂閱中的節目列表。目前是大約 100 檔節目。但是我不可能全部都聽完。

但是數據去哪裏找呢？

我用的 Podcast App 叫做 Castro，裡面有個打星 (Star) 的功能。這個計畫本來是想要做打星列表，公開出來。但是 App 裡面沒有匯出的功能，備份檔裡面雖然有節目和單集的歷史紀錄，但只有內部索引號碼 (UUID)，讀不到節目名稱。去信開發者也只收到罐頭回信。

本來很氣餒，但後來找到有人透過祕技把資料庫匯出，寄送到自己的 Email 信箱。基本上他做的是把事件灌到另一個紀錄個人嗜好的 App 裡面。

有了原始資料庫就可以做很多事情了，包括收聽行為的分析。拿到了資料庫之後，就用 SQL 和 Google 試算表做簡單的數據分析。剛好遇到日本的黃金週，旅遊計畫也因為武漢肺炎 (COVID-19) 疫情而被取消了，所以我有完整的長假可以玩這些資料。（技術細節請見文末）

以下是一些 Insights。直方圖的數據是根據收聽時間 × 節目主要語言來彙整的，以一週為單位，橫軸是收聽的週（以週日為開始），越往右邊越靠近現在（2020 年 5 月）。

數據最終更新的時間是五月初，所以五月的數據不完整。以及我開始用 Castro 大約是 2018 年 11 月，所以先前的數據是空白的。不過一年半的數據也夠分析了。

總播放單集數

首先最直覺的問題是「我到底都聽了多少單集」。

跟其他 Podcast App 不同，Castro 的基本設計是一個播放清單和收件匣 (Inbox)。Castro 把訂閱 Podcast 節目類比成訂閱電子報，有新內容的時候先進入收件匣，要聽的時候再移入播放清單，且可以自由調整播放順序。我在 Castro 中設定大部分的節目是進入 Inbox，只有少數每日更新，或是乾貨特別多的節目，可以直接進入播放清單。如果你是播客主，Castro 客戶端的下載 +1 就是發生在此刻。

如果用 SEO 的術語來說，就是「閱覽數」(PV)。除了我有信心可以每集必聽的節目之外，還有標題內文吸引我所以點了下載的單集。聽說 SEO 界還有所謂的 clickbait 伎倆——以聳動或嘩眾取寵的標題騙人家點進來看，增加 PV 及增加廣告曝光次數。幸好 Podcast 仍然還在主動訂閱的模式，clickbait 比較難奏效。

以下這張圖就是我自己的 PV 數。

• 雖然華語佔了超過一半，但是英語的佔比也不少。現在大致上中國、台灣跟英語的節目很平均。
• 很明顯有個趨勢是收聽的英語單集越來越多，甚至一度超越華語節目。但如今大概還是保持在 30~40%。
• 我訂閱了好幾檔每日出新番的 NPR 英語節目，如 Coronavirus Daily、The Indicator from Planet Money、Short Wave等，所以這也讓英語（黃色區塊）變得比較大片。另外比較積極更新的還有 Vox 的 Reset、中國的故事 FM等。
• 2020 年 3 月間，一週播放到 100 個單集似乎是有點太超過了。這段期間是我大量試聽不同的新節目。
• 2019 年底開始，台灣的華語節目大爆發。可能是為了試聽所以點了許多單集，但是現在佔比又被中國華語吃回來了，這可能跟我自己喜好的節目風格有關。
• 只要我去外地出遊就幾乎不聽，如 2019 年日本黃金週連假、新年連假。
• 2019 年 9 月開始聽節目的時間突然變得很多，這是因為我把 PlayStation 4 賣掉了。

總播放時長

上述的播放單集並沒有回答一個問題：我播放了那麼多的單集，加起來到底都花了多少時間在聽 Podcast？

透過統計資料庫裡面的「播放進度」就可以算出每週大約播放了多少小時的節目。當然因為它只有進度（秒），所以它是原始音訊檔的時間長度，忽略快轉跳過的時間、加速播放、自動移除空白而省下的時間，也忽略了重複播放多次的加總時間（只計算最後一次播放到哪裏）。但因為我的習慣通常是不會重複聽第二次，所以不精確的部分不太影響這個指標。

那麼來看圖說故事。縱軸是加總的播放進度，單位是小時：

• 儘管之前的單集統計說明我聽的節目是中國華語、台灣華語、英語平均，但從總播放時長來看，還是中國華語居多，可能我收聽的中國節目大部分都很長。
• 2020 年 2 月中開始，因應武漢肺炎疫情，公司要求我們在家上班。從那之後我聽節目的總時長一度下跌，但是後來又漲回來了。我猜測是跟我沒有通勤有關，所以花了一些時間建立新習慣。
• 2020 年 3 月中曾經一度達到一週 60 小時，相當於平均一天超過 8 小時。原本我以為我程式寫錯，去看了原始資料還真的都有印象。可能是一邊開著一邊工作，當白噪音，其實也沒在認真聽。這種節目就是我該退訂的。
• 2019 年中以前聽的內容大部分都是中國的節目
• 儘管台灣的節目變多了，進入我耳朵的聲音大部分還是中國的節目
• 從 2019 年 7 月開始重拾英語收聽習慣，但最近有被台灣節目排擠的趨勢
• 2020 年 4 月開始聽了一些台語節目，基本上都是從中央廣播電台的閩南語頻道來的
• 日語節目我曾經多次嘗試，多次放棄

追新番指數

上述的收聽及紀錄不考慮新番舊番，也就是說如果我在 2020 年 5 月選了 2018 年發布的單集收聽，還是算在 2020 年 5 月。如果要解答訂閱的即時收聽量，也就是「新番一定聽」和「訂了沒在聽」的指標，則要考慮發布日期和收聽日期。

下圖計算的方式是每週有給一個節目按「播放」就算 1 次，按多次也只算 1 次。並且只計算發布後 7 天內收聽的節目，所以可以排除去聽老集數的誤差（播客主所謂的「長尾」）。

於是就可以看出每週真正去追的新番數量：

• 儘管台灣節目大爆發時期我訂了許多台灣節目，但是隨後也退訂了不少，反而新訂了一些中國的節目。再度強調，這還是跟我個人收聽的口味有關。
• 真正大量追番的時期要從 2019 年 9 月算（賣掉了 PlayStation 4）；在此之前大概都在每週 10 檔節目左右。也是在幾乎同一時期去追了不少英語節目。
• 目前（2020 年 4 月）是維持在每週追 40~50 檔節目。將來應該會變少。
• 我所謂「訂了 100 檔節目」真正有持續在追的也只有一半。事實上可能有很大一部分已經停更了，不是我主動跳過的。

忠誠指數

上面的追新番圖表是照語言區分的。我事實上最好奇的是「我需要退訂哪些節目」。

做播客主的人一定會好奇：你的節目真的有人在聽嗎？儘管託管網站後台看得到下載數量，但你卻不知道他們有沒有播放（除非是 Apple Podcasts、Spotify 等平台有第一手數據）。甚至你也不知道這其中有多少是訂了之後沒在聽。

接下來這項統計，就是我對節目的忠誠度。這個數據是如此計算的：

對於每一檔節目，找到最初我播放的單集。從那之後發布的每一單集，根據月份加總時間長度。然後和我實際收聽的長度相除。

這樣就能得到一個「消化率」：雖然有訂閱，而且它在這個月有發新番，但有多少 % 是我真正去聽了。

這就能看出我對節目的忠誠度，以及看看那些我可以退訂，反正我也沒在聽。

再一次用 SEO 的術語來解釋，前文的單集總數如果是 PV 的話，忠誠指數就是「逗留網站時間」。吸睛的標題可能會吸引我打開網頁，但真正有內容的長文會讓讀者流連忘返，標題卻不見得吸睛。

然而對於 Podcast 來說，花時間製播的內容還是得要有人聽完才有意義。標題和節目筆記只是一種廣告，轉化發生在節目的消化。但這樣的轉化除非是發布端到收聽端整合的大平台（Apple Podcast, Spotify）才能精確計算，不像 YouTube 有製播-回放-統計一條龍的鏈，用 RSS 發布的 Podcast，天生就很難一個平台通吃，一般的泛用型 Podcast App 因為單純是下載檔案，後端只能看到下載數據，無法向播客主回報收聽紀錄等資訊。所以這種數據對播客主來說是夢寐以求的。

以下這張截圖只是一張試算表的一部分。因為 5 月的內容還算新，所以我還沒聽完。但是如果我往下捲，就會發現許多紅色、有發新番但根本沒在聽的節目。截圖中的節目基本上都是我還有固定在追的。

當然，因為有語言的標籤，所以可以照語言分類：

我的積極目標是要讓最新月份的數據盡量在 70% 以上，或是偏綠色，這表示我有訂的都有在聽，盡量降低出一集就 Skip 一集的壓力感。

後記：用數據洞察自己的沈迷

運用大數據平台分析個人的「小數據」也不是第一次了。在 2019 年 11 月也做過類似的事情，那時候是分析 Twitter 發文紀錄。資料量也不是很多，才三萬多條 ，不過已經可以看到一些有趣的趨勢。

今天做這個 Podcast 分析，雖然最初的目標是拉出資料庫來發布我的打星播放清單，但是當我手上拿到一個充滿事件紀錄的資料庫的時候，我就轉而運用我在工作學到的知識來分析數據，以及把流程給自動化。

從 2019 年末開始我有觀察到，每週推出的單集，多過我可以消化的量，但當時不以為然，只覺得 Castro 可以幫我統整單集，我自己決定如何收聽，已經比 Overcast、Pocket Cast 等基於播放列表的 App 來得方便了。但最近看到 Inbox 有 40 個單集，我就感到問題的嚴重性。儘管在家工作的時間變多了，但同時我也開始覺得「聽不完」，那麼 Podcast 作為娛樂工具就失去了它的意義，不如說是一種沈迷。

以前我也有類似的感覺。2012 年以前我沈迷 PTT。2016 年以前我沈迷日本動漫，每季都會追新番，看不完。2019 年以前會玩 PS4 的暢銷大作。2019 年中以前會一直逛 Facebook。如今是 Podcasts。

雖稱沈迷，這種沈迷卻不是因為樂在其中，而是來自怕落伍的壓力 (Fear of Missed Out, FOMO)。我只是一味地輸入而沒有咀嚼之後再輸出，為的只是保持自己的資訊跟「大眾」同步。如果讀新聞是為了因應瞬息萬變的世界（瘟疫下更重要），那麼追逐娛樂的新事物，雖然可以消化時間，有時還能改變自己的思考模式，但如果沒有輸出，並無法給自己帶來好處，只是徒增壓力。

我依稀記得 Cal Newport 在《Digital Minimalism》一書中闡述一種觀念，就是我們要去尋找對自己最有效用的科技，而非單純別人也在用所以你也用。狂刷 Netflix、社群網站等行為，都不是最有效用的利用法。作者建議讀者去尋找對自己最有效用的科技，並對於任何新科技都保持嚴格檢驗的態度，「我是否確實體會到他對我生活帶來的美好」、「我榨取了它對我最有價值的部分了嗎」而非不假思索地接受新科技。

用台灣人最愛說的 CP 值（性價比，Cost-Performance Rate）來解釋的話，成本（代價）是你花了多少時間在這些娛樂，但最重要的性能（效能）卻是可以自己定義的。它可以是消遣無聊的生活、創作而得到的爽、對世界發表意見的輸出。但如果成效不彰，可能你用的方法不適合你，也可能該工具本來的設計就不是讓你爽，而是讓你看廣告，所以吸引你的注意力。但最重要的是，定義一個效能 P，然後檢視你付出的代價 C 跟實際獲得的 P 有沒有夠高，藉此來檢驗科技是否給自己帶來好的效果。

話說回我自己。如前所述，我放棄了不少興趣，動漫、電動、SNS。近來我跟 Netflix、電子書處於一種我很滿意的平衡，我也找到了我和 Facebook 新的平衡。但眼看 Podcast 好像快要吃垮我自己，現在做這種數據研究，給自己一些未來的指引，可能還不遲。

附錄：技術細節 for Geeks

分析的方式：

• Google Spreadsheet 樞紐分析表 （TIL 這根本上古神器）
  • 原本還用了 =QUERY() 但發現我要的結果直接用樞紐分析表即可
• Amazon Athena 寫一些 View Query 倒 CSV 出來
  • 目前是手動取代成 TSV 然後貼到 Google 試算表，因為還要 workaround 節目標題裡面有逗號的情形
  • 最終可以從 API Gateway 從 S3 直接出 CSV 檔案，用 =IMPORTCSV() 直接匯入 Google 試算表
  • 最終還可以掛入 Step Functions 來自動下 query 更新 CSV 檔案
  • 學到了 PARTITION OVER 可以得到類似樞紐分析的結果

資料彙整的方式：

• 用一支程式跑在 Lambda 抽出 SQLite 資料到 JSON，每個 Query 上限 1000 條，避免一次拉太多導致 Lambda memory bloat；盡量用小規格機器跑。
• Schema 寫在 AWS Glue Table 裡面，手動寫，沒有用 Glue Crawler。
  • 手寫一來是因為可以直接抄 SQLite 的 schema，二來是原始資料庫有一些欄位可以手動 cast，例如時間戳記原本是 integer，可以 cast 成 timestamp。
  • Glue Crawler 爬一次要兩分鐘，也是錢。
• 語言的標籤是我在 AirTable 手動加，然後複製貼上到 Google 試算表的。根據的是節目主要語言，而非單集語言。所以如果一個台灣的華語節目突然有一集在講英語，那算在台灣華語。由於出現的次數很低，不影響整體結果，所以不予區別。

下載資料庫檔案的方式：

• 祕技是在 Castro > Settings > Support 那邊長按 Email Support，就可以選擇 Email with Database and Logs。因為我的資料庫有36MB，所以只能用 iCloud Mail Drop 寄送。
• 用 Zapier Email Parser 抓出 iCloud Mail Drop 的下載地址
• 讓 Zapier 執行一段 JavaScript 打到一個 API Gateway 執行 Step Functions
  • API Gateway 可以發 API Key 比較方便
  • Step Functions 不需要讓 client 等 Lambda 結果，直接回 execution ID
  • Zapier JavaScript Task 的 timeout 是 1 秒
• Step Functions 的內容：
  • 第一個 Lambda 開 Puppeteer 尋找 iCloud Mail Drop 附件的下載地址；規格比較高
  • 第二個 Lambda 直接用 axios 讀 stream 丟到 S3
  • 因為 Puppeteer 的 Chromium 要下載檔案比較麻煩，無法確定檔案何時下載完成，必須一直 poll 下載資料夾，直到沒有 *.crdownload 為止。
  • 最後一步是啟動另一個 Step Functions 把 S3 裡面的資料庫檔案變成 JSON（如上述資料彙整）。分開是為了讓第二個 state machine 不要跟下載綁在一起，這樣要抽資料就可以直接從 S3 讀現成的資料庫。

一些淚：

• 嘗試用 AWS SAM 寫 Node.js 程式，一開始蠻順利，到後來發現 sqlite3 有系統依賴，在 macOS 上面 sam build 的話會編譯成 macOS 用的 binary，無法跑在 Lambda 的 Linux 上面。必須用 sam build -u 跑在 Docker 裡面編譯才行。但是非常慢。
  • 既然拿得到下載網址，也許可以直接寫一個 Docker image 跑在 Fargate 然後直接 wget + sqlite3 | jq + aws s3 sync 就好了。
• 要寄送 Castro Support Email，iOS 必須有 Mail App。其他第三方 App 不行。
• 因為要從 iCloud 下載檔案，以及連結 Zapier，服務都開在美區似乎網路延遲比較低。
• CloudFormation deploy API Gateway 似乎不會 deploy stage。

一些懸念：

• 不知道 Castro 什麼時候會把這個輸出資料庫的功能下架。
• 結果我還沒做打星播放列表。

最近受到《Digital Minimalism》觀念的影響，理解到過度使用社交網路會影響身心健康及工作效率，於是有意識地拒用社交網路（希望有機會寫一篇文章談談拒用的歷程）。不過因為被 Twitter 提醒週年慶，也開始好奇，11 年來我用 Twitter 的習慣有什麼改變。

結果就是花了半天的時間做出這張圖表：

Series 的定義如下：

• 1.0_regular 單純發文
• 1.1_link_fwd 轉貼連結
• 2.0_retweet 單純轉發別人的推文
• 3.0_reply 在 Thread 中回覆別人

其中有幾個明顯的低谷，主因是農曆過年我不太上網。

而 2017 年中起我發文的量變得很低，主因是我換到一個做得很開心的工作，牢騷變少了，自然發文也就變少了。這也反映了我一直都把 Twitter 當牢騷垃圾桶的心態。

最後是 2019 年約 7 月起急劇降低，這是我開始實踐 Digital Minimalism 的時期。不過上個月（10 月）好像快破功了。

一些高峰值我不願意去深究，我猜可能是年輕氣盛跟人家在網上吵架吧。

接著就來講講我是如何做出這張圖表的。

取得 Twitter 的資料

要做分析，首先要有資料。一開始想說是不是要寫機器人去爬 API，但事實上 Twitter 提供個人數據下載服務，在 Your Twitter Data 頁面可以索取下載。這服務應該是來自一些國家政府的要求，Facebook 也提供一樣的功能。

Twitter 稱下載回來的資料是 JSON 格式，但實際上卻是封裝在 JavaScript 程式碼裡面。聽不懂？舉個例子：

這是 verified.js 的內容：

window.YTD.verified.part0 = [ {
  "verified" : {
    "accountId" : "9999999999",
    "verified" : false
  }
} ]

這是我期待的 JSON：

[ {
  "verified" : {
    "accountId" : "9999999999",
    "verified" : false
  }
} ]

每個檔案都是長這樣。眼尖的 JavaScript 工程師應該看得出來，前面多了 window.YTD.xxx.part0，你得丟進 JavaScript Runtime 把檔案都 evaluate 一遍才能得到資料，還得事先初始化 window.YTD.xxx object，而且是存在記憶體裡面。

而像我這種每天發牢騷的 Twitter 用戶，至今累積 3.7 萬條推文，下載回來的數據就相當可觀。我的 tweet.js 高達 48 MB。整包丟進 Runtime 再寫程式分析是很不切實際的事情。

不過好在這些檔案除了開頭是一個 assignment 之外就都是 JSON 了，全都是 primitive types，statement 最後面也沒有分號（😉），所以直接取代開頭也就行了：

sed 's/^window.YTD.tweet.part0 = //g' < tweet.js > tweet.json

灌到資料庫裡

為了高效率搜尋和分析，我需要把資料灌到資料庫裡面。當然我有好幾個選項：我可以開一個 ElasticSearch 直接灌進去，也可以刻 Schema 灌到 PostgreSQL 裡面，甚至把所有 JSON structure 都打平丟進 Excel 也可以。

不過以上幾個方法都比不起找一個雲端大數據分析服務來得簡單，雖然很像用牛刀殺雞。我一開始選擇了 Google Cloud 的 BigQuery，而且發現它很符合我當下的需求，所以就沒有研究別的方案了。

首先要灌資料。在 Console 開一個 Data Set 很簡單。灌資料就有點問題了。你可以從本機上傳，但是上限是 10MB。我有 48MB 的 JSON 要傳，只能透過 Google Cloud Storage。然而它又有一個限制：JSON 必須是 newline delimited 的。

這是一般的 JSON Array:

[
  {
     "a": 1
  },
  {
     "a": 2
  },
  {
     "a": 3
  }
]

這是所謂的 newline delimited：

{"a": 1}
{"a": 2}
{"a": 3}

沒錯，就是一行一個 object，用換行符號 \n 切開。

要把上述的 tweet.json 轉換成 newline delimited 格式，只要用 jq 即可：

jq -c '.[]' > tweet.gbq.json < tweet.json

現在你可以上傳檔案到 Cloud Storage 並匯入資料了。

欸，那 Schema 呢？免煩惱，只要打開自動偵測即可！

Auto detect
☑️ Schema and input parameters

分析資料

GCP 的 BigQuery 是可以用 SQL 分析的。大致上跟一般的 RDBMS 一樣，只有 function 之類的不太一樣。以下是我是用的 SQL。

首先是做一個 view 來拉出我分析要用的 metadata。用 Query editor 玩玩看，然後按 Save view 即可：

SELECT
id,
parse_datetime("%a %b %d %X +0000 %Y", created_at) as timestamp,
starts_with(full_text, "RT @") as is_retweet,
in_reply_to_user_id IS NOT NULL as is_reply_thread,
ARRAY_LENGTH(entities.urls) <> 0 as has_links,
full_text --- 肉眼參考用，實際分析不會用到
FROM `<table>` --- 這裡取代成你的 project.dataset.table

長得像這樣：

幾個注意的點：

• created_at 匯入是 String type，原文如 Wed Mar 02 12:34:56 +0000 2018 ，時區固定在 UTC。BigQuery 不會幫你自動轉換成時間，所以自己 parse。
• 所有的轉推，包括官方轉推，都是 RT @ 開頭。但是 entities.urls 裡面會包含原推的超連結。所以 is_retweet 和 has_links 會同時 true。

畫圖

View 弄好之後就可以對它下 Query，例如：

select
timestamp,
if(is_retweet, "2.0_retweet",
  if(is_reply_thread, "3.0_reply",
    if(has_links, "1.1_link_fwd", "1.0_regular")
  )
) as tweet_type
FROM `<view>`
order by id asc

上文提到 is_retweet 和 has_links 可以同時 true，為了畫圖方便起見，我用了一個有點複雜的 if() 來決定哪個優先。

Query 下好之後你應該會發現有個按鈕叫做 “Explore with Data Studio“。這就是我拿來畫圖的工具。你可以把 Data Studio 想像成 Excel 的圖表工具，只是它的資料源是 Google Cloud Platform 的某個 source。

為了方便肉眼閱讀，我設定了這些：

• Dimension: Year Month (Show as: YYYYMM)
• Break Down Dimension: tweet_type
• Break Down Dimension Sort: tweet_type, Ascending（這也是我加了 1.0 等數字的原因）

Data Studio 提供了許多圖表可以用，像題圖的 Stack Area：

或是Stacked Bar， 可以看出我沒有 Monday Blue 但有 Thursday Blue ：（Dimension Format 設成 Day of Week ）

或是 Pie Chart，證明了我真的是轉貼魔人，近 60% 是轉推和分享連結：

結論：數據要分析才有意義

現在的工作上會碰到一些 SRE（System Reliability Engineering）的挑戰，需要設事件、做 log pipeline，在大量的雜訊裡找到系統有問題的訊號。我不是負責 SRE，但我需要負責送 event 出去，好讓他們可以分析。如果套到 Twitter 歷史資料來看的話，每一個近況更新（推文）都是一個事件，metadata 自然是有意義的，但拉長遠來看，我也可以得知自己上網習慣的變化。附帶一提，如果透過自然語言分析去處理內文，也可以建立自己想法的模型跟情緒，這也就是為什麼劍橋分析事件中，他們可以針對某特定族群下假訊息的廣告，也是為什麼你應該小心那些臉書小遊戲和算命 app。

雖然這裡展示的工具是 GCP BigQuery + Data Studio，但實際上應該有很多工具可以做到同樣的事情。身為 Web 工程師，SQL 對我來說沒什麼困難，但人工匯入資料建立 schema 是我不太想花時間做的事情，這也是我選擇 BigQuery 的原因：它可以自動偵測 schema。

可惜當初刪除 Plurk 的時候沒有下載備份，現在要分析也沒辦法了。就當作過往雲煙吧。

比本名重要的日語發音假名轉寫

我初到日本時的居留證裡面並沒有漢字姓名，只有護照上的拼音「Chuang Yu Cheng」，順序比照日本的姓前名後。這就成了我的正式名字，因為日本的政府機關和金融機構只承認居留證上寫的姓名，即使出示護照也不被認可（但是台灣刻的漢字印章被承認了）。真正「取回」漢字姓名的時候，已經是更新在留期限（居留期間）拿到新的居留證的時候了。

但除了漢字或是羅馬字的姓名之外，日本生活中會很常被問到「姓名的日語發音」。實務上是替原本的姓名（不管是什麼文字）加註日文的假名發音，表單上會標記「セイ・メイ」或「フリガナ」等。舉凡銀行開戶（關係到公司的薪水能不能轉到你的戶頭，以及自動扣帳能不能成功）、年金、甚至網上預約餐廳、理髮店等，很多情況下會被同時要求填寫「姓名和假名發音」這樣的組合。

對於日本人來說，看到羅馬字拼寫的姓名，第一反應就是用熟悉的英語來讀。我的拼音姓名照字面用英語讀的話，「Chuang Yu Cheng」就變成了「チュウアン・ユーチェン」。我聽說過有些人會用這種方式開戶、註記戶籍的別名，一方面也可以省很多麻煩，畢竟羅馬字照英語的發音對日本人來說很直覺也不陌生。

然而，畢竟我是和日本人一樣擁有漢字姓名的，就算不被官方承認，心底總是堅持要有一個跟自己漢字姓名有關聯的名字。於是我便給自己取了一個非正式名字，是中文姓名的日語發音。中文名字是「莊育承」，日語音讀裡變成了「そう・いくしょう（Sou Ikushou）」。從台灣或中國來日本的人，有不少人會採用這種發音。如「王」讀如「おう（Oh）」、「陳」讀如「ちん（Chin）」。

而這種規則當然也不是我發明的。在日本的新聞報導中，出現華人姓名的時候，發音大部分是日語音讀。如蔡英文成了「さい・えいぶん（Sai Eibun）」，賴清德成了「らい・せいとく（Rai Seitoku）」，而習近平就成了「しゅう・きんぺい（Shu Kinpei）」，偶爾會讀成「シー・ジンピン（Shee Jinpin）」，但機率不高。也就是說，現代日語中本來就有用日語音讀去讀華人漢字姓名的習慣，我取用日語音讀當姓名發音，應該是合乎文化習慣的。這也很符合漢字文化圈各自用當地發音規則的習慣，畢竟我們台灣人也擅自用國語發音直接讀日本人、韓國人，甚至香港人的名字。

那麼實際上有遇到什麼障礙呢？可以說並沒有太大的障礙。事實上，連銀行都承認了我自己取的日語發音。首先銀行在我開戶時接受了，後來不管是薪資轉帳、辦信用卡、投資帳戶、自動扣繳帳單，只要假名一致，就沒有問題（更精確地說，是被銀行的電腦結清系統受理了）。可以說，假名拼寫的一致性，比姓名是漢字還是羅馬字還重要。

於是「そう・いくしょう」就變成了我的半正式姓名。

而我可以擅自取發音，我認為，這跟日本的姓名文化有關。

名從主人的日本姓名發音原則

在日本生活三年來我注意到，日本人對於姓名的漢字該對應什麼發音，並沒有很嚴格的要求。

在台灣的國語裡，一個字基本上只有一個讀音；若有兩個音的話，會被稱為「破音」，也就是說國語重視由官方指定的正確的發音，超過方言發音。舉個例子，小時候我的國語課本裡「滑稽」的「滑」發音是「ㄍㄨˇ」，最近的課本變成了「ㄏㄨㄚˊ」。如果考試寫「ㄍㄨˇ」還會被批錯，可見官方發音的強勢。

然而在日語裡，一個字並不一定只有一個發音；即便是音讀（日語仿漢語的發音），也可能因為自中原傳入日本的時代不同，而有有所差異。如果拿我姓氏「莊」的日文常用漢字「荘」去查的話，會得到「しょう」（莊園、莊嚴）、「そう」（別墅、旅館、也可用在宿舍名）、「チャン」（麻將連莊）等發音。剛剛提到的「滑」，常見的就有「かつ」、「なめ」、「すべる」，而「滑稽」一詞的發音則是「こっけい」。

實際上人名和發音的對照也並不是一對一的。拿「新垣結衣」的名字「結衣」（ゆい）來說，常見的漢字還有「優衣」、「由依」等，但是發音都是相同的。又如「大野智」的名字「智」（さとし），同樣發音的漢字名也有「聡」、「智史」、「里志」等。類似的例子不勝枚舉，但在日本人的名字文化裡是很普遍的。

也就是說，日本人自己的姓名漢字和發音本來就是分開來的，不止正式的文書需要標記發音，連商業名片上都會註記發音。在社交場合，也無法光從發音去猜漢字——通常是拿了名片或加對方好友才發現漢字是如何如何寫；更不會隨便從漢字去猜發音，這恐怕比猜錯漢字還沒禮貌。在不知道漢字的情況下，直接在書信上寫假名其實是可以接受的。

日本人其實對於人名漢字與發音之間的連結並沒有像台灣有那麼嚴格的要求，基本上是尊重個人選擇的漢字發音的對應（當然漢字有法定的准用字集，但是包括了許多傳統漢字和異體字）。於是我也可以搭順風車，我說「莊育承」讀作「そう・いくしょう」不會有人反對，我說「Chuang Yu Cheng」讀作「そう・いくしょう」連銀行都同意了。這也讓我有辦法把在身分證件沒有漢字名的情況下，硬是把我的名字和漢字名連結起來。

尊重人名，不應做任何假設

上述的文化現象，有時候對於非日本文化出身的外國人，可能會遇到困擾。初到日本的外國人得先把自己姓名的日文發音和寫法背起來，即使她不需要日語能力就能夠工作生活。我遇到最大的一次麻煩，就是開辦證券帳戶時，系統規定漢字的姓、名最多加起來八個字。當時我的居留證還沒有漢字姓名，只能輸入羅馬字母。超過八個字的部分怎麼辦呢？該券商還提供了一個問答項目，解釋外國人該如何填寫（答案是名寫頭文字，姓寫到七個字滿，如 “CHUANG Y”），這顯然是系統設計當初只考慮日本人的問題。過兩天券商來電詢問我的全名，結果還是用我自己取的假名開戶了。

當然在台灣開發軟體系統可能也會遇到類似的問題。別以為每個人的姓名都是三個字、頂多四個字，2018 年中華民國行政院的發言人「谷辣斯・尤達卡」就有六個字呢，更別說著名的「黃宏成台灣阿成世界偉人財神總統」那可是他的正式名字。

曾經看過一篇使用者體驗的技術文章說，做人名輸入的 UI，除非法定要求，最好是一個很長的輸入框即可。不要分姓和名，不要假設全家都同一個姓，不要假設每個人都有姓氏（日本皇室沒有姓），因為對自己最直覺的人名輸入框，可能只適用於自己的文化，而在那成千上萬不同的文化裡，總有你不知道的人名文化。擅自設計各種人名輸入的限制，只是徒增困擾而已。再說，人名怎麼寫，真的對自己的業務有影響嗎？

「ユーさん」

說了這麼多，實際上同事、朋友們又會有另一套叫法。除了最常見的禮貌叫法「そうさん」（姓+さん）、外國人居多的情況叫「ユーチェンさん」（讀如英語 /You Chain sang/），有一段期間我還被叫做「ユーさん」，來源是羅馬字的「Yu-Cheng」的「Yu」。

似乎有不少人以為有連字符的名字是可以分開的，固然西方文化裡面有這種姓名用法，但台灣人的名字連字符寫法，單純只是把兩個漢字的發音分開而已。中國漢人的姓名並不流行用連字符，整體看起來就是一個單字。在我觀察到連字符問題之後，我也就學中國人用「Yucheng」這個寫法了。只是有些人會覺得連字符是一種台灣人的特徵——或說「民國遺風」吧——拿掉連字符似乎就失去了台灣人的文化。當然這就是見仁見智了。

如果我護照上的名字是台語發音，又會是怎麼樣的風格呢？

但與 1989 年昭和改平成不同的是，21 世紀的生活大量依賴電腦資訊系統，尤其是商業活動、政府和銀行，因此作業系統和應用軟體將不得不支援新的年號，堪稱「日本的 Y2K 問題」。在經產省的網頁上，可以找到一份日本微軟的技術說明會簡報 (PDF)，裡面提及了不少他們將如何支援新年號的問題，使用者可能會遇到的問題，以及哪些舊軟體將不支援新的年號。例如，Excel 自動填滿日期的時候應該要在 2019/5/1 換新的年號、官方採用「元年」而非「1 年」。某些本地化模組也將支援西元和和曆的自動轉換。

其中我比較關注的是合字的文字編碼問題，在這裏特別拿出來講一下。

年號的合字

日本的年號其實是有合字 (ligature) 的。什麼叫做合字呢？基本上就是多個字合起來變成一個字。在活字印刷時代，會把常用的組合鑄成一個活字，例如 fi 有一個 fi 的合字。Unicode 裡面也收錄了不少人類文明史上的合字，包括日本明治以來的年號合字：

• ㍾ (U+337E) = 明治
• ㍽ (U+337D) = 大正
• ㍼ (U+337C) = 昭和
• ㍻ (U+337B) = 平成

因應新年號實施，Unicode 當然也要給這個合字一個碼位。不過「㍻」前面的 U+337A 已經被指定了，「㍾」後面的 U+337F 也被指定了（㍿），只能選一個別的區段，最後 Unicode 決定保留 U+32FF 給新年號的合字用，但是無法立刻發布新版本。因為 Unicode 編纂合字時，會一併紀錄合字拆開來是哪些字，這稱為正規化 (Normalization)。例如「㍻」的拆解就是<square> 5E73 6210 [ ‌平 ‌成 ] 。他們的計畫是在年號公布之後儘快發佈 Unicode 新版本。

此外字型也需要支援這個字符。在上述的微軟技術簡報中指出，Windows 內建字型，包括從別的廠商買來的授權，將近 30 套字型需要支援這個合字。並且還有直排橫排要支援。而 Adobe 動作也很快，在新年號公布之後，已經開始更新 Adobe Fonts 的字型了。

在作業系統內有安裝新版字型的情況下，應該可以看到如下的合字：

• ㋿ (U+32FF) = 令和

或是參考這個示意圖：

年號合字的來源

這些合字是怎麼來的呢？為了寫這篇文章我上網搜尋了一下。細節可以參考這篇 Shift_JIS 編碼名稱的故事 和 Adobe 官方的日本年號合字簡史。

1982 年，日本微軟和當時的一些系統廠商制定了 Shift_JIS 碼表來在 16 位元 OS 裡表示日文（關於制定的歷史可以看一下維基百科）。在 MS-DOS 裡面稱為 CP932。微軟開放了其他 OEM 廠可以任意擴張字元，於是 NEC 和 IBM 就各自加入了自己的字符。年號的合字就是 NEC 加進去的。

1993 年 Windows 3.1 問世時，微軟禁止其他廠商任意擴張字元，並把 NEC 和 IBM 自己加入的字符都統一了。這個新的碼表叫做 Windows-31J，在 MS-DOS 系統內部依然是 CP932，直到今天。

有趣的是，上述的微軟技術簡報中明確指出，Shift_JIS 將不支援新年號「令和」的合字。也就是說，如果文件是採用 Shift_JIS 編碼，又剛好用了「㍻」等合字，那麼新年號是鐵定無法支援的，除非貼圖（像前文的示意圖）、自行造字，或是放棄合字，改用兩個漢字。

關於更換年號的時程

根據現行日本國憲法，天皇無權干政，而頒布年號是政府的職權而非天皇本人，並僅限於皇位繼承。（承襲自明治時代所規定的一世一元制度，以前日本也像中原傳統一樣，會因天災人禍甚至君主心情而改年號）。

跟以往因天皇駕崩而在當日改元有所不同，這次政府希望盡量降低社會成本，而打算提早公布。不過政府內的保守派基於避免兩個權威的原則，希望可以當日公布並實施。最後協調的結果是登基一個月前的 4/1 公布新的年號。

政府は当初、改元の準備期間を長くとるため今夏ごろの公表を検討。しかし、新元号の発表によって天皇陛下と新たに即位する皇太子さまという「二重権威」が生じるとの懸念が強まり、公表時期をできるだけ即位日に近づける方向となった。

——《朝日新聞》 2018年5月17日 大久保貴裕

至於為什麼是 4/1 呢？據說是微軟向政府要求的。原本政府想要在 4/10，天皇在位 30 年紀念活動隔日，即 4/11，公布新的年號，但 Windows 有固定的更新時程，是每個月的第二個星期三。2019 年 4 月是 4/10。如果不在那之前發布更新檔（註冊表），就只能等到 5/8 了。

同（マイクロソフト）社は毎月１回、第２水曜日に全世界統一でソフトの更新を行うが、４月は１０日、５月は８日となる。政府は当初、４月１０日に開かれる天皇陛下ご在位３０年の「お祝いと感謝の集い」の翌１１日に新元号の公表を検討していたが、１１日ではソフト更新に向けた改修作業が次の５月８日まで行うことができず、同月１日の改元には間に合わない。

——《産経新聞》2019年1月4日 小川真由美

如果屬實的話，微軟果然是世界的巨頭啊，連日本年號的發布日期都受他們的影響😂

但話說回來這次平成的天皇明仁生前退位，也是在 2016 年他老人家發表了「關於象徵天皇之務的想法」的演講，說他身體撐不下去了，但是依法他無法干政，也無法自行宣布退位，懇請各位國民體諒。言下之意就是拜託政府立個法讓我讓位吧。他也許也預想到自己若自然辭世，必然會重演 1989 年當時社會無法因應新年號的問題。這次可以平順地過度到新的年號，我認為是他給日本社會最大的禮物之一。

年號與西元的轉換

日本作為世界上少數採用自有年號的國家，外界可能不太清楚年號是怎麼在日常生活使用的。事實上日本的年號是以日為單位的。

例如昭和換平成的時候是 1989/1/7 駕崩，1/8 起採用新的年號。也因此在正式的文書裡面，記載和曆生日是需要看日期的。1989/1/7 以前出生的人是昭和 64 年，1/8 以後出生的則是平成元年。這也反映到了網上金融系統，如線上申請信用卡的網站，會同時有昭和 64 年和平成元年的選項。

而年度的區分則還是照陽曆年末年初的規則，所以令和元年是從 2019/5/1 到 12/31，到 2020/1/1 就是令和 2 年了。

前大日本帝國最後一次更改年號是 1926/12/25 大正改昭和，而 1926/12/25 既是大正 15 年也是昭和元年。該從幾點幾分切開我沒找到，但大概也不重要了吧。真要探究的話，當初日本帝國還有兩個時區（台灣屬於 GMT+8 西部標準時），那麼當地幾點幾分開始算昭和呢？也是個會讓人想破頭的問題吧。

最初用了 Rails 推薦的 JBuilder，沒考慮到效能，QA 也不覺得慢，就沒注意。結果 APM 統計出來數字很難看，某特定 endpoint 的 rps < 2（requests per second），就開始認真調查了。

首先是發現 SQL 花的時間很長，極端狀況下甚至會 timeout。仔細一看才發現是 schema 的 nesting 太深，四五層左右，還有重複內容的 array。這是 OpenAPI Schema 互相嵌套的潛在問題，錯在當初 review API spec 沒仔細審 schema。這種四五個表格互相 join 我是不會調 SQL 效能啦。但實際上看前端 UI 也沒用到，就跟前端工程師協調把那些 array 直接放空，終於可以拉到 rps 3 以上了。

但還是很慢，就想說改用別的 JSON Serializer。首先選的是 ActiveModel::Serializer，速度立刻翻倍。但 AMS 的 API 有點醜，bug 也不少，他們自己甚至把整個 gem 砍掉重練；我的話是要在 root 加料的時候很麻煩。但看在速度的份上還是用下去了。這樣子 rps 拉到了 5 以上。直接擺脫 ActionView 的 Template 果然是正確的選擇 — — JBuilder 似乎每 render 一次 partial 就會重新開一次檔案，時間都浪費在 disk I/O；而 class 的話一啟動就存在記憶體裡面了。

不過在找 JSON Serializer 的時候，固然發現到其他 gem。其中一個叫做 panko_serializer，是用 C 寫的，號稱有特別的優化（關於 type casting）。效能是 AMS 的兩倍，該當 endpoint 的 rps 拉到了 10 左右，要在 root 加料也很簡單。缺點是嚴重依賴 db column 的 raw 值，只能輸出 UTC 時間（除非改用 method 叫），而且有隱藏的「如果不是 db column 就會變成 nil」的問題。加上專案本身還很新，感覺維護成本很大，就放棄了。

最近試的是 ActiveModel::Serialization::JSON#as_json，就是真正內建在 Rails 裡面的那個。搭配 Oj encoder 的 Rails 優化功能的話，速度只差 panko_serializer 一點點（5% 左右）。該 endpoint 測出來大概 8 rps 而已。

原本覺得他的 API 很難看，沒有 Serializer 好讀；但是仔細看了一下其實也沒什麼難懂，基本上就是事先用 hash 寫靜態的 structure。指定 association 的方式也很簡單，也因此比較容易發現多曾嵌套問題。

panko_serializer 的 attribute-only 問題他也有，但是 API 文件寫的比較好讀，事前指定 call instance method 就行了。缺點是不能設定 attribute alias，必須 method alias 寫在 Model 裡面，然後當作 method 去拉。

此外沒有對 association 加工的功能（前文提到我需要把某個深深的 array 清空），其他 serializer 或 Jbuilder (view) 都可以寫 if-else 來處理。不過好在 as_json 拉出來就是 hash，反正對這個 hash 用 yield_self或 tap 加料就好了。

另一個隱藏的問題是，如果 association 是 nil，那麼他連 key 都不會寫進去，JSON Schema validator 就在唉了。我不知道這是 bug 還是 feature 啦，總之是 hash 嘛，對他加料即可。

測試的工具是 wrk，之前還用過 Apache Bench (ab)，但覺得 wrk 直接指定單線程刷 n 秒看 rps 比較直觀。都不喜歡的話可以參考 awesome-http-benchmark 這個列表找自己喜歡的即可。

至於最近很紅的 Netflix 的 fast_jsonapi，我沒用它，因為有個要件：你的 API response 必須是 JSON:API 格式（有固定的 meta attributes 要套上）。我們的 API 很不巧並不是 JSON:API 格式，所以不能直接上。曾經我參加過一個 workshop 號稱改用 fast_jsonapi 就可以效能翻不知道幾倍，結果我看他的 code 根本就一堆 N+1 問題，修掉 N+1 就翻倍再翻倍了。更別說原本他的 API 也不是 JSON:API 規格，效能翻倍之前先逼死前端吧。

以上就是我把 API 效能提高近 10 倍的故事。結論是

1. API Spec 的 schema 多層嵌套是 red flag
2. 直接刷 API endpoint 測效能
3. 慎選 JSON Generator
4. 效能不佳，先解 SQL 效能
5. 世界上沒有 silver bullet。別人的場景跟你不見得相同

看一個都市的歷史總是有許多東西可以學習跟比較的。例如民生用水在技術上是怎麼引進都市的，在公共水井取水的婦人會趁機會交換八卦（井戶端會議；日文維基百科的社群討論區也叫做井戶端）。以及一些重要的地名：

• 井之頭：神田上水的源頭，玉川上水開通前最主要的水源
• 溜池：曾有天然湧水池，也是江戶城外濠的一部分
• 水道橋：跨河道的引水渠道

有些竟然還有浮世繪，可以更具體地想像當時是長什麼樣子的。

但回家路上反覆咀嚼時，我感受到一件事：我喜歡在日本看歷史博物館，也許是為了尋找他們跟台灣的關聯。

在台灣，要得知正確的歷史很困難，由於政權更迭、文件佚失、故意隱瞞等原因，現代充斥著許多穿鑿附會、以訛傳訛、張冠李戴的假歷史。你跟他們指正嘛，也不見得會認真對待，甚至回以不要那麼認真、見仁見智之類的幹話。最有名的大概就是台北瑠公圳了。

目前最可信的產業史還是日本時代遺留下來的產業遺跡，我想是因為不少在日本其實都可以找到類似的東西。例如在明治時代的東京，曾經有淀橋淨水場（今東京都廳，當地也是 Yodobashi Camera 的發祥地），類似的東西就是公館水源地的淨水廠，而水源市場的名字也是來自當時的水源地。

在我看來，台灣人是一個庶民文化長期被殖民國忽視的族群，今天佔主流的中華文化還是某種程度上鄙視庶民文化。日本有浮世繪紀錄庶民生活，台灣的文化卻有不少是缺乏可信紀錄的。日本經歷過政治動盪，但是沒有被征服過；台灣經歷了許多次的政治清洗。失去的東西固然很難找回來，但至少可以在別國找到一點線索。

也就是之前在推特看到的說法：喜歡去日本玩的台灣人，有些也許是羨慕日本人還保留了他們自己的歷史文明。

應該反省為什麼會失去、該如何保留這些僅存的文化遺產。我想這是歷史博物館教我最多的東西。

身為現役 Web 工程師，資訊安全不只教條，還是必須在生活中實踐的原則。近來 Facebook 的帳號安全事件，給了我動力去清查所有用 Facebook 登入的第三方網站，並且積極把 Facebook 登入方案從其他網站刪除，或加上密碼登入。本文分享我的動機，以及實踐後的結果。本文雖然針對 Facebook，但也適用於 Twitter、Google 等社群網站帳號登入，只是我用 Facebook 登入的網站特別多，所以以此為例。

沒有永遠的 Facebook 帳號

從 2007 年開立帳號以來，見證了 Facebook 從默默無名的美國留學生通訊錄，到取代無名小站，躍身為台灣兩大社群服務（另一個是 LINE），大企業行銷不能忽略他的廣告平台，靠他的快速登入和廣告集客力起家的小新創更不知幾許。商業之外，其快速發酵的效果，與昔日的網路論壇 PTT 互相呼應，也促成台灣在 21 世紀的第一個大型民主運動。可以說，Facebook 已經成為台灣現代流行文化的一部分了。

然而 2018 年初，Facebook 帳號安全問題頻傳。台灣國內有批評中國政府便被刪文甚至封帳號而逃到 Twitter 的臉書難民，在其本營美國則有 Facebook 疏於保護個人資訊任其流竄的醜聞。儘管 Facebook 是來自言論自由的國度、來自世界資訊科技首都矽谷，無論是政策上跟安全技術上都值得信任，但就像矽谷新創九死一生（字面意義），世界上沒有永遠的公司，沒有永遠安全的系統，當然也沒有永遠流行的網路服務。

這裏就有了一個動機：萬一我的 Facebook 帳號被封，或是 Facebook 倒閉，至少希望其他網站不能受到影響。

沒有永遠破不了的網站

大家都愛「Facebook 登入」。使用者喜歡他簡單好用，產品經理喜歡他有效提升轉換率。但如果你不是 Web 工程師，首先要知道的是，在一個網站上按下「Facebook 登入」後會發生什麼事情。

當你從「Facebook 登入」完成註冊之後，技術上可以做到，你不需要輸入個別的帳號密碼就可以登入那個網站。網站會拿到一個 Facebook 帳戶的識別號碼，大部分情況下還會拿到 Email 地址，網站可以透過這兩個東西來驗證你就是你，因為可以透過 Facebook 驗證。

但你有沒有注意到，某些網站會同時要求你提供「好友名單」來幫你配對已經在同一個網站上註冊的好友。既然要配對，就需要取得好友名單，這很合理。但要知道的是，就算你沒有打開該網站，網站還是可以自動去下載好友名單來配對。

此外連生日、學經歷、照片等等，甚至你發表在塗鴉牆跟社團裡面的內容，都可以取得，端看你當時允許了網站使用那些資訊。這有好的用途，也有壞的用途。理論上網站必須要盡量減少取得的資訊，但有些初級程式設計師沒有資訊安全概念，寫出會取得所有資訊的程式，這是問題，然而最大的問題不在於取得多少資訊，而在於「如何安全保存這些資訊」。

要知道，「網站資料外洩」這種事情是很常發生的；通常是網站資料庫遭駭客入侵而整個被下載，所以俗稱「拖庫」。如果連製作網站的工程師都有可能因為疏於管理而發生拖庫等資安事件，作為一般使用者的我們，又怎麼能夠相信網站上的資料不會被駭客拖走呢？即使軟體資訊安全上沒有問題，那麼監守自盜的問題呢？

這裏就有了另一個動機：為了避免網站隨意取得我的私密資料。

不再有共用密碼帶來的風險

我以前會積極使用 Facebook 登入的主要原因是，通常不需要設定密碼。我也開發過這種程式，很清楚這是怎麼設計的，而且並不只是不需要，而是「沒必要」設定密碼。不想設定密碼的原因是我無法記住不同網站的密碼。大家都知道，共用密碼是很危險的。一個網站被拖庫，你不知道他的密碼是明文還是單向加密，萬一是明文，那麼你就等著其他網站的帳號都被駭吧。所以，以前凡是遇到小型網站或是新創公司的服務，我都盡量用 Facebook 登入。另一方面也是方便。

不過理論上，只要不跟其他網站共用密碼，這個風險就不存在了。然而在沒有密碼金庫軟體的時代，這幾乎是不可能的事情，畢竟我的記憶力沒有好到可以記住數百個不同的字串。但今天，瀏覽器甚至作業系統已經內建密碼金庫，我也已經用 1Password 好多年了，新註冊的網站幾乎都是直接採用隨機密碼，然後存入金庫。能開通多重認證的就都盡量開通，再有什麼網站被駭，都可以高枕無憂。

既然當初積極使用 Facebook 登入的誘因已經有更好的解決方法，那麼何必再使用 Facebook 登入呢？這是第三個動機。

逐一清查 Facebook 登入帳戶

要知道你授權了那些網站可以取得你的 Facebook 資料很簡單，打開「應用程式設定」就可以了。此前我隱約記得有登入過很多網站，但沒想到竟然超過一百個。下圖是我已經刪了一半時才想起來要截的圖，之後這些應用程式有一半被我刪掉了，可見當初真的太隨便就按登入。

逐一點開每一個應用程式的圖示，就可以知道該程式可以取得那些資料。大部分都是個人基本資料（姓名、性別、大頭貼、是否成年，無法拒絕）以及 Email、生日。有些會要求現居城市，有些要求了好友名單，求職相關的會要求學經歷等等。但如果仔細看看這些網站的內容，會發現他們不少都會要求過多的資料。例如並非基於地理資訊的服務，也要求提供居住城市；並未基於年齡或生日促銷，卻要求提供生日；並未提供強社交功能，卻要求提供好友名單等等。

這裏最麻煩的在於「逐一點開」。Facebook 的這個管理頁面並不提供讓你一眼就看出那些應用程式有什麼權限的功能。如果你像我一樣有一百個，那就得老老實實地按一百次。

然後你就有機會發現有些應用程式幾乎可以看光你的資料呢：

刪除那些不再想透過 Facebook 登入的網站

綜上所述，本次清查 Facebook 登入的目的在於：

• 避免登入被限制為 Facebook 導致一家死全部死的問題（單點故障）
• 朕的資料是朕的資料，朕不給的你不能拿（停損）
• 實踐一個網站一個密碼的獨立密碼

在逐一清查的過程中，我發現有太多當初為了省事而直接點 Facebook 登入的網站，而且有太多是我無法相信他們的系統是安全的。所以本次清查，理想的情況下要達到以下目標：

• 對於不再使用的網站，刪除帳戶；若無法刪除，至少撤回資料使用權
• 對於頻繁使用的網站，設定 Facebook 以外的登入方式，最好是密碼登入

然而事情不是那麼簡單。

想換密碼登入，請找後門

雖然有些網站可以讓你設定密碼，但帳號管理畢竟不是主要的業務功能。至今遇到這幾種情況，根據難易度排序，最簡單的在上：

1. 在透過社群登入的情況下，可以設定密碼，之後允許刪除社群登入連結
2. 在透過社群登入的情況下，可以設定密碼，但無法刪除社群登入連結
3. 在透過社群登入的情況下，也只能更改密碼，但我並沒有「舊」密碼，只能透過「忘記密碼」來設定新密碼
4. 在透過社群登入的情況下，無法設定密碼，但是可以透過「忘記密碼」來設定密碼
5. 在透過社群登入的情況下，無法設定密碼，也無法透過「忘記密碼」來設定密碼

看到沒？這真的是很罕見的需求呢，連常見的帳戶管理程式庫都沒有好的支援。其中 1 跟 2 算是最容易處理的，就算無法刪除社群帳號連結，還是可以從 Facebook 應用程式管理頁面直接吊銷，杜絕網站今後取得更多資料。

3 跟 4 是產品經理該負的責任，但畢竟可以繞一圈設定密碼，雖然不直觀。

5 完全是鎖死的的情況，你在這個網站只能用 Facebook 登入。要是你的 Facebook 帳號被刪除，那麼你就跟這個網站無緣了。因為這些網站很不對用戶負責任，我只好列在這裡：

• Expedia （找不到設定密碼的方式）
• Funliday（不提供密碼登入）
• Product Hunt （僅提供 Facebook / Google / 母公司 AngelList 的登入）
• TAAZE 讀冊生活（因為是 Facebook 帳號，無法設定密碼）
• 旅行酒吧（因為是 Facebook 帳號，無法設定密碼；去信客服手動更換）
• 蝦皮購物（需要台灣手機號碼接收認證碼，尚未核實）

沒有永遠的用戶

有些網站當初註冊是抱著嚐鮮的心態，現在沒在用了，最好能刪就刪。不少日本網站都直接提供「刪除帳號」（退会）的服務，這當然輕鬆許多，至於真的刪除與否，姑且信之。但大部分其實是不提供的，尤其是美國跟台灣的新創網站，只好如前文所述直接吊銷 Facebook 連結。

此外還有些竟然把 Facebook 登入的程式整個移除了，讓我想了一下才知道如何透過「忘記密碼」來登入。

沒有永遠的網站

網站還活著的還能處理，但有些竟然是倒閉了，或是工程師做的玩具網站，沒在維護，上網搜尋也找不到，不知道該從哪裡登入。

仔細想想，這種情況下才更應該用獨立密碼登入，畢竟是玩具網站，安全性跟隱私原則都是不明的，其中一個竟然還是未加密的 HTTP。

其中印象最深刻的是 aNobii，這個曾經的愛書人的集散地，現在還有人在用嗎？這個服務據說數年前被義大利的出版商買下了。現在你再去登入，就會發現網站翻譯做的很糟糕，混合了義大利文(?)跟繁簡中文，連密碼重設信件都是我看不懂的文字，得靠網址才能猜得出來。

最嚴重的問題在於 aNobii 的 Facebook 登入是授權「所有資料」，跟上述的 PlayStation Network 一樣，是非常要不得的。要不是這次做檢查，大概也不知道是這種危險的情況。

結語：不想給人看的東西就別授權給人看

我花了一整天清查一百多個 Facebook 登入的現況，最後還保留的只剩下 27 個。有那些會偷偷在後台下載「最新資料」，又有那些會拿這些資料去做各種所謂的調研，我無從得知。在 Facebook 成為台灣第一大公眾社群網站的現在，我們不知不覺在 Facebook 上寫了許多，你以為沒價值，但對於某些人來說很有價值的資料，也在不知不覺中，透過這種與外部網站的連結，流到第三方的手上。很多時候我看到有人在玩占卜遊戲，都覺得資訊安全真的要從小教育，但應用軟體的世界變化太大，該怎麼讓非專業人士的大眾了解，真的非我能力可及。

最後我竟然開始認同日本人消極使用 Facebook 的心態，感覺那是一種自我保護的行為。

The new SDK on Firefox 57 implements WebExtensions, a W3C Standard for web browser extensions. WebExtensions is mostly based on Chrome’s Extension API. I don’t know much about the history of the standard war, but the old SDK on Firefox, Jetpack, in my opinion is easier to learn than Chrome’s.

Although I already have a Chrome version which is mostly based on the WebExtensions-like API, it doesn’t mean that the same source code works on Firefox. There are some pitfalls I encountered during the re-development. In fact, this project eventually grew into a practice on how to write once and build extensions for different browsers.

The full source code is available at chitsaou/copy-as-markdown. Please check the code if you’re interested, and feel free to give me any feedbacks.

Callback vs Promise

If you check MDN’s WebExtensions Chrome compatibility article, the first thing you’ll notice is the difference of function signatures: Chrome uses callback, and Firefox uses Promise.

For example, the [chrome|browser].runtime.sendMessage API, which sends message from popup window to the process the extension is running, has different usage between two browsers:

// In Chrome
chrome.runtime.sendMessage(payload, (response) => {
  // ...
})

// In Firefox
browser.runtime.sendMessage(payload).then(response => {
  // ...
})

Although Firefox accepts callback on functions that supports Promise, I still feel it easier to do things with Promise. But Chrome does not return Promise on those function calls. What’s worse, Chrome uses chrome as the global API entrypoint, while Firefox uses browser but supports chrome.

Fortunately Mozilla provides a polyfill library to do all the dirty jobs: mozilla/webextensions-polyfill. As the name states, it makes Chrome to support browser object, and make all the functions calls return Promise.

Now I can just write browser.* and use the nice Promise-based APIs that Firefox recommends. Perfect!

By the way, if you submit an add-on with this polyfill library, Firefox Add-On developer dashboard will warn you about unnecessary library. But it can still be published without removing the library.

Clipboard Access

Copy as Markdown helps you generate Markdown code for links and images, and copy it to the clipboard, so clipboard access is the most important part.

Unfortunately, if you want to do copy in the extension environment, for now there is no API allows you to do so with a single function call. The only way is this:

// create a <textarea>
let textbox = document.createElement("textarea")
document.body.appendChild(textbox)

// set content
textbox.value = "text you want to copy"

// select all texts and execute 'copy'
textbox.select()
document.execCommand('Copy')

Further more, in Firefox, you can only do this in content script or popup window. The background of this limitation is that, in order to create a textarea, it must be attached to a document. In WebExtensions, the core code of extension is running in a “Background Page”, a web page that get started when extension is loaded. If you open Task Manager in Chrome, you’ll see each extension running as a process, and they’re actually the Background Page of each extension.

There are many limitations on what you can do in Background Page, and some are browser-specific. In Firefox, one thing you can’t do is document.execCommand() , because the event must be dispatched from a user interaction, as the MDN article Interact with the clipboard says. So say you want to make an extension that shortens the current tab, the easiest way to do so is using a Browser Action Popup.

So how can we solve this? The answer is Content Script. Even you cannot copy text in Background Page, you can still do so if you inject a Content Script into the current page. The only downside of this solution is, you cannot inject Content Script into certain pages for security reason, such as Firefox Add-on website, and all the Firefox internal about:* pages. Therefore, Copy as Markdown for Firefox sometimes doesn’t work if your current tab is a Firefox-restricted page.

Permission

In addition, to enable clipboard copy in Firefox, a permission is required in manifest.json:

"permissions": [
  "clipboardWrite",
],

This permission is required if you want to copy something in Firefox, but not required for Chrome — you can copy text in Chrome even if this permission is not specified — . In fact, when I (accidentally) released the first beta for Chrome, some user reported that there are “extra permissions required”, because I added clipboardWrite in Chrome build. Although there is nothing more I requested for the new version, it still scared the users. So then I decided to remove it from manifest.json . After all we don’t need that.

Now in the code I can do such switch: (see full source code here)

import copyByBackground from "../../lib/clipboard.js"

function copyByContentScriptWithTabWrapping(text, tab) {
  if (!tab) {
    return browser.tabs.getCurrent()
      .then(tab => copyByContentScript(text, tab))
  } else {
    return copyByContentScript(text, tab)
  }
}

let copyText = null;

if (ENVIRONMENT.CAN_COPY_IN_BACKGROUND) {
  copyText = copyByBackground
} else {
  copyText = copyByContentScriptWithTabWrapping
}

As you can see there is a ENVIRONMENT.CAN_COPY_IN_BACKGROUND. How do I feature-detect if the browser supports copy in Background Page or not? Well, I don’t. Instead I build separate targets and specify their behavior, as described in “Webpack” section below.

Native Popup Style

In Firefox Jetpack, there was no popup window that you can display when user clicks a button on toolbar. — Well, at least there was no such thing when I was building my first Jetpack add-on. — But in WebExtensions framework, there is a popup, and there is a CSS framework for you to make it look native. All you have to do is enable it in manifest.json :

"browser_action": {
  "browser_style": true
}

The style it applies is basically the same as Firefox Style Guide. I use samples from Navigations to make menu items in the popup look native.

For Chrome, there is no such CSS framework you can use, but I’ve been using a custom style for a while. The first thing I have to do is to change some CSS selectors. But the hard part is how to load my custom CSS in Chrome. Fortunately, we can use a common practice from the web development world: load the CSS file anyways, namespace the CSS selectors, and append body-level class conditionally.

First, the CSS file is always loaded, no matter what browser it is. It’s loaded locally, so doesn’t cost network bandwidth. (Conditionally inserting <style> to load CSS dynamically does not re-draw the page, though.)

In CSS, namespace everything so that it won’t match until the top-level element has some class:

.custom-popup-style .panel-list-item {
  /* ... */
}

.custom-popup-style .panel-list-item:hover {
  /* ... */
}

In popup page’s JavaScript, change the <body>'s class according to a environment variable:

if (!ENVIRONMENT.SUPPORTS_POPUP_BROWSER_STYLE) {
  document.body.classList.add("custom-popup-style")
}

That’s all. Thanks to all the responsive web designers for this tip.

The ENVIRONMENT.SUPPORTS_POPUP_BROWSER_STYLE is also done by Webpack, which will be covered below.

Webpack for Multiple Targets

As I mentioned in the previous sections, Copy as Markdown is now built by Webpack. Although you can develop an extension without Webpack, it still brings some benefits such as module loading and separating environments for browsers.

Module Loading

Separating code by module makes it easier for maintenance. All you need to do is pack scripts into single files, such as background.js , popup.js and content-script.js, and reference them in manifest.json.

You may heard that ES6 module is available in the latest Chrome, but unfortunately it is not available in Chrome Extension environment, because it requires HTTP server to return application/javascript MIME Type, but Chrome extension does not do so for JavaScript files (yet?).

But even if ES6 module is fully supported, there are still some other benefits we can get from Webpack.

Defining Environments

As mentioned above, the extension needs to know whether the browser supports two features: copy in background page, and popup style.

At first I thought it makes more sense to do a real feature detection, like:

function canCopyInBackground() {
  try {
    // ... setup textbox
    document.execCommand('copy')
    return true
  } catch {
    return false
  }
}

But it doesn’t work, because document.execCommand does not throw error when it fails. If I instead validate it by checking the clipboard content, that brings critical privacy issues.

Now because this extension is only shipped to 2 platforms: Firefox and Chrome, and I can lock supported browser versions during publishing, why not just build two packages for those two browsers?

With Webpack it’s easy to do so, just use webpack.DefinePlugin and load different environment files according to command line environment variable.

Separate manifest.json

Besides, we can also separate manifest.json for different browsers. As mentioned above, in manifest.json there are some different keys and values between two browsers. Some keys trigger warnings, some would even trigger permission alert to users. My solution is make two files manifest.firefox.json and manifest.chrome.json , and conditionally copy one of them to the target directory, with copy-webpack-plugin.

Although it may make more sense to use shared manifest.json and modify the JavaScript object dynamically during build process, I didn’t find a good plugin doing this well, and I feel that maintaining two manifest files is a good solution for now. I’ll leave the issue there until there is a 4th browser to support.

One of the benefits of doing so is that, Chrome Web Store and Firefox Add-On have different rules on version numbers and names (described below). This fact makes it hard to use the same version number between Chrome version and Firefox version. Separating manifest.json makes it easier to set different version numbers that are compatible to different publishing platforms.

Publishing on Stores

Firefox: Keep the Original Add-on ID

Once you finished switching to WebExtensions, one thing you need to do is to keep the original Add-on ID from previous version. To find it, just visit the add-on dashboard. Then specify it in the new add-on’s manifest file:

"applications": {
  "gecko": {
    "id": "jid1-xxxxxxxxxxxxxxxx@jetpack"
  }
}

Those jid and jetpack terms are from previous Add-on SDK Jetpack. You have to keep to same ID so that Firefox Add-on can recognize it as the same extension.

However, this key is invalid in Chrome, so, another reason to use two different manifest files.

Version Name Incompatibility

These issues are not directly related to framework switching, but a problem that exists for a long time. If you’re new to Chrome Web Store, then this section may be helpful.

On Chrome Web Store, all versions must contain only digits. For example 1.2.3 is valid, but 1.2.3rc1 is invalid. On Firefox Add-ons, they accept beta versions like 1.2.3rc1 or 1.2.3beta, and it will recognize these as “Development Version”, so you can ask your friends to test it before release.

For Chrome, there is another version_name to display a different version name in Chrome’s Extensions page. While I am doing public testing, the version I used for Firefox Add-ons is "version": "2.0.0rc1" , but for Chrome I have to use "version": "2.0.0", "version_name": "2.0.0rc1" . Firefox does not allow version_name manifest key, though.

What’s worse, Chrome strictly check if newly uploaded extension is versioned greater than the previous one. Say you want to publish a beta version, you cannot publish a 2.0.0rc1 . Instead you can use 1.99.0 . If you accidentally published 2.0.0 as a development version, like me, the next version can only be 2.0.1 or “greater”.

That’s why my final release version becomes 2.1.0. Even if I want to publish a “stable release of 2.0.0” I can never do so because I have already uploaded a 2.0.0 to Chrome Web Store.

Beta Testing

Finally, there is no “Beta Testing Channel” in Chrome Web Store. Well, there is, but it’s too complex for me to figure out how to setup a test user group.

On Firefox Add-ons, there is a Development Channel for beta testers. If the add-on contains version with beta or rc it will be recognized as development version, and published into Development Channel. This is a big plus to add-on developers.

In fact, I accidentally released a broken version 2.0.0 on Chrome Web Store, which I thought it won’t be published due to misleading copies. There is no way to take down a version, and no way to “revert” to older version. All I could do is check out to older version in Git repository, increase version number to 2.0.1 (due to strict restriction on incremented version number), set version_name to something like reverted to older version, zip it, and upload to Chrome Web Store. Sounds crazy, huh?

There are many things that Chrome Web Store could be improved. I just heard that they’re rebuilding the developer dashboard recently. Looking forward to see the new platform.

Conclusion

WebExtensions is a utopia for browser extension developers. Write once, run everywhere. But different browser vendors may have different preferences on things like API design, features and security concerns. I tried to run my extension on Edge, unfortunately it failed to even get loaded.

This is another example of browser diversity, but it’s much harder to develop something on it, due to limitation of web API supports, and tools / libraries we can use. I believe that in the foreseeable future, browser vendors can accomplish the ideal goal, but for now, we still need to handle many browser-specific issues.

By the way, when will Safari support WebExtensions?

Accented Latin and Kana File Names Finally Work as Expected in APFS

To try these out, you can download a sample code from chitsaou/apfs-docker-unicode-poc.

Consider you have the following files in your Docker project:

$ cat café.txt
I like Moonbucks Coffee!

$ cat ありがとう.txt
ありがとう means Thank You!

And a simple Dockerfile:

FROM alpine:latest
COPY . /

Put these files under an HFS+ disk. Build the image and run it:

$ docker build -t test-image .
$ docker run test-image cat café.txt
cat: can't open 'café.txt': No such file or directory
$ docker run test-image cat ありがとう.txt
cat: can't open 'ありがとう.txt': No such file or directory

The file will not be accessible if you type its name with the keyboard in your terminal or source code. (To type é, press Opt-E then e)

However, if you build the image from an APFS disk, it will work. First, create an APFS image and mount it:

$ hdiutil mount foo.sparseimage -mountpoint /Volumes/apfs-image
$ cd /Volumes/apfs-imagehdiutil create -fs APFS -size 1GB foo.sparseimage

Copy the files above into it, and try again:

/Volumes/apfs-image $ docker build -t test-image .
/Volumes/apfs-image $ docker run test-image cat café.txt
I like Moonbucks Coffee!
/Volumes/apfs-image $ docker run test-image cat ありがとう.txt
ありがとう means Thank You!

It works! ✨

So if you have to handle file names with accented Latin characters, or even Japanese characters in Docker, you can simply wait until the APFS’s final release, or convert to ascii-only representation like cafe or Romaji. You can also avoid HFS+ by building the images on a Linux-based CI server, instead of macOS.

The rest of this post will briefly describe the reason why it doesn’t work on HFS+, with some Unicode knowledges.

Problem of File Name with Combined Chars in HFS+

Say that we have a file named café.txt, and we know each char’s Unicode code point as well as it’s UTF-8 code (note that é char is a two-byte C3 A9 in UTF-8; read this if you want to know why):

   Unicode     UTF-8
c   U+0063      0x63
a   U+0061      0x61
f   U+0066      0x66
é   U+00E9      0xC3A9
.   U+002E      0x2E
t   U+0074      0x74
x   U+0078      0x78
t   U+0074      0x74

Now let’s see how it’s represented in HFS+:

$ touch café.txt
$ ls *.txt | od -t x1 -c
0000000    63  61  66  65  cc  81  2e  74  78  74  0a
           c   a   f   e    ́  **   .   t   x   t  \n

We can see that the 4th byte is 0x65 (e) followed by 0xCC 0x81. What exactly is this CC 81? If we reverse it from UTF-8 we’ll find that it’s [U+0301](http://www.fileformat.info/info/unicode/char/0301/index.htm) Combining Acute Accent.

On the other hand, in Docker AUFS:

$ docker run -it alpine sh
# touch café.txt
# ls *.txt | od -t x1 -c
0000000   c   a   f 303 251   .   t   x   t  \n
         63  61  66 c3  a9   2e  74  78  74  0a

This time we get a C3 A9 code sequence, which matches the UTF-8 code of é char.

And if we try it in APFS:

/Volumes/apfs-image $ touch café.txt
/Volumes/apfs-image $ ls *.txt | od -t x1 -c
0000000    63  61  66  c3  a9  2e  74  78  74  0a
           c   a   f   é  **   .   t   x   t  \n

This time we also get a C3 A9 sequence, the same as that in a Docker AUFS disk.

So why is there such difference?

Unicode NFD: How HFS+ Represents é and が

As shown above, the representation of é in HFS+ is 65 CC 81 rather than UTF-8’s C3 A9 . This form is called Unicode Normal Form Canonical Decomposition, or NFD, while the C3 A9 form is called Normal Form Canonical Composition, or NFC. With NFD, é will be represented as e followed by ◌́ (U+0301).

You can read more on Wikipedia’s “Unicode equivalence” article.

In HFS+, a file name will be encoded in Unicode NFD form. It seems that when Docker builds an image, the file names are copied as-is. So if we have a file named with characters that were converted to NFD on HFS+, and copy it to Docker, it will not be accessible via the most commonly used NFC form.

But it will work if the file is copied from an APFS disk. Since APFS does not convert file names into NFD, the file names are the same as what we have typed into the terminal or source code.

How does Apple File System handle filenames?

APFS has case-sensitive and case-insensitive variants. The case-insensitive variant of APFS is normalization-preserving, but not normalization-sensitive. The case-sensitive variant of APFS is both normalization-preserving and normalization-sensitive. Filenames in APFS are encoded in UTF-8 and aren’t normalized.

HFS+, by comparison, is not normalization-preserving. Filenames in HFS+ are normalized according to Unicode 3.2 Normalization Form D, excluding substituting characters in the ranges _U+2000_–_U+2FFF_, _U+F900_–_U+FAFF_, and _U+2F800_–_U+2FAFF_.

Source: Apple File System FAQ

Voiced Kana (Daku-on)

In fact, this NFD conversion also happens in Japanese.

There are 2 kinds of scripts in Japanese: Kana (仮名) and Kanji (漢字). Kana, with around 100 characters, are mostly used for the Japan-origin phrases like ありがとう (thank you), or loan words like ハンバーガー (hamburger), while Kanji is a set of characters shared with the East-Asian culture sphere.

Some Kana chars have two sounds: 清音 (sei-on, means voiceless) and 濁音 (daku-on, means voiced). For example, コ /ko/ is sei-on, and ゴ /go/ is daku-on. The way daku-on is represented in Japanese is by adding a double-dotted dakuten mark at the right-top corner of a sei-on Kana. Such contract is similar to the unvoiced and voiceless contrast in English, for example “coat” /kot/ vs “goat” /got/, where /k/ sound is unvoiced, and /g/ sound is voiced.

In most cases, sei-on and daku-on are individual characters in Unicode, for example, コ is U+30B3, and ゴ is U+30B4. However, it can also be represented in NFD form, so ゴ becomes コ followed by ◌゙ (U+3099 Combining Katakana-Hiragana Voiced Sound Mark). Now let’s go back to our original issue…

Voiced Kana Representation in HFS+

Say we have a file named ありがとう.txt . The third character が is the one with voiced sound mark. Their Unicode representations are as follows (Mind that chars other than .txt are all encoded as 3-byte sequences in UTF-8, so you can find it later in the byte sequence):

    Unicode UTF-8
あ  U+3042  0xE38182
り  U+308A  0xE3828A
が  U+304C  0xE3818C
と  U+3068  0xE381A8
う  U+3046  0xE38186
.   U+002E      0x2E
t   U+0074      0x74
x   U+0078      0x78
t   U+0074      0x74

Now let’s inspect it in HFS+: (try this in sh rather than bash)

$ touch ありがとう.txt
$ ls *.txt | od -t x1 -c
0000000    e3  81  82  e3  82  8a  e3  81  8b  e3  82  99  e3  81  a8  e3
          あ  **  **  り  **  **  か  **  **    ゙  **  **  と  **  **  う
0000020    81  86  2e  74  78  74  0a
          **  **   .   t   x   t  \n

You can see が is encoded as E3 81 8B E3 82 99 , while E3 81 8B is U+304C か, and E3 82 99 is U+3099 ◌゙ , the voice mark.

Let’s try again in Docker AUFS:

$ docker run -it alpine sh
# touch ありがとう.txt
# ls *.txt | od -t x1 -c
0000000 343 201 202 343 202 212 343 201 214 343 201 250 343 201 206   .
        e3 81 82 e3 82 8a e3 81 8c e3 81 a8 e3 81 86 2e
0000020   t   x   t  \n
        74 78 74 0a

This time we get a E3 81 8C code sequence, which matches the UTF-8 code of が character.

And if we try it in APFS:

/Volumes/apfs-image $ touch ありがとう.txt
/Volumes/apfs-image $ ls *.txt | od -t x1 -c
0000000    e3  81  82  e3  82  8a  e3  81  8c  e3  81  a8  e3  81  86  2e
          あ  **  **  り  **  **  が  **  **  と  **  **  う  **  **   .
0000020    74  78  74  0a
           t   x   t  \n
0000024

The same E3 81 8C sequence as in Docker AUFS.

Again, if we build a Docker image and copy the file from a HFS+ disk, it won’t be accessible, because when you type ありがとう it is usually in NFC form, not NFD. But if we do so from an APFS disk instead, it will work.

That is, the accented Latin problem happens during Docker build, will also happen in the Japanese file names.

Alternative Solution: convmv

There is another solution that you can use: converting file names from NFD to NFC during build process, but adding such workaround just for macOS (development machine) spends too much effort with no much return, and makes it harder to maintain. In my case, I eventually renamed all Japanese file names to ASCII-only names (Romaji, romanization of Japanese). After all, Japanese people are familiar with Romaji.

You can take https://gist.github.com/JamesChevalier/8448512 as an example. But as far as I tried, it doesn’t work well for the Japanese Kana.

One More Thing: Atom Git Status

I’ve been using Atom for more than 1 year. There was an issue annoyed me for some time, but has been resolved during my research of the Unicode file name thing.

Suppose you have a Git repository, and there is a file named café.txt .

In Atom’s tree view, it is always displayed as new (green), even if git status is clean.

But if the repository exists in an APFS disk, it won’t be displayed as new after checked into the repository.

Conclusion

Understanding how texts are encoded in the computer system is always fun. I remember that when I was young, I learned that BIG-5 (encoding system used by Traditional Chinese) is double-byte, and there is a famous 許功蓋 (Hsu-Kong-Kai) problem, in which these characters uses \ as the second byte, causing a string to be recognized as escape character like \“ and crash a compiler or a database system. When I was studying in the college, I learned how UTF-8 encodes Unicode efficiently while keeping the compatibility with ASCII. They must be very smart to come up with such idea.

I studied this problem by Google and try-n-error, found no good explanation so I wrote this. If you found anything wrong or you’d like to add more, please point out in the comments!

See also

• Apple File System — Frequently Asked Questions
• Different utf8 encoding in filenames os x
• 日本の文字とUnicode 第3回 | 大修館書店 WEB国語教室

以往為了應付 Windows 而必須先把檔案名稱轉換成 Big5 才能讓他們在 Windows 正常解壓縮。這種做法很可能會遇到 Unicode 轉換到 Big5 失敗的問題，例如游錫堃的「堃」在 Big5 裡面就沒有，這時候就需要想很多 workaround。

但如果你面向的使用者很少，例如公司內部用的系統，解法會比較簡單。rubyzip 不知到哪時候開始提供了一個可以讓新版的 Windows 直接認出 Unicode 檔名的方法：

files with non ascii filenames — rubyzip/rubyzip _rubyzip - Offical Rubyzip repository_github.com

簡單來說，這樣設定就行了：（Rails 的話開一個 initializer 即可）

Zip.unicode_names = true

凡 Windows 8 以上的版本都沒問題。檔案總管內建的解壓縮工具就可以了。

至於如果你要支援 Windows 7 以下，或使用者不固定⋯⋯Good luck 😂

同樣的問題本來我已經 6 年沒處理了，但最近來到日本，又要應付 Shift_JIS 的問題。看來 legacy encoding 真的是到哪裡都很煩的問題。

作為一名全職程序猿，為了讓自己維持效率和健康，無時無刻都在思考如何改善自己的工作環境跟工具。以往我在乎的是工具的好壞，好比說電腦一定就是 MacBook Pro 配 16GB RAM、鍵盤就是 Realforce、用 Magic Trackpad 而不用滑鼠、螢幕首選 Dell、有錢有空間的話就敗一台 Aeron 全功能椅，搭配 Bose QC25 抗噪耳機、fripSide 全專輯來讓我不會被外界干擾。

當我還在台灣有那些閒錢的時候，都會儘量自我滿足奢侈的工具慾。然而當人到了日本之後——或說已經決定不續留台灣之後——大部分的東西都成為累贅。大件的東西都在離開台灣之前處理掉了，真正帶來日本的只有 MacBook Pro（SpoonRocket 遺產）、Realforce 鍵盤和 QC25。

然而有一天我突然發現 Realforce 鍵盤有一個 switch 可以交換 Control 和 Caps Lock，也附了兩種尺寸的鍵帽，又同時發現我自己在輸入大寫字母的時候，幾乎都是按 Shift + 英文字母了。Caps Lock 對我來說就像 Application Key 那樣毫無用處。

再加上聽說過 Unix 鍵盤最早的時候 Control 是在 A 左邊的，作為一個每天使用 Terminal 的程序猿，^C ^K 每天按，長年受到左手小指發麻的困擾。也聽說有不少人為了這件事所以把兩個鍵交換。於是我乾脆也試著把這兩個鍵給交換，結果的確大幅改善了左手小指發麻的症狀。

具體來說，把 Control 移到 A 左邊之後，這些習慣改變了：

• 按 Control 不需要再大幅移動小指頭 → 最常按的 ^C 可以很輕鬆就按到
• 更強迫自己用 Shift 去輸入大寫 → 發現幾乎只有文案的句首才需要大寫，程式碼的話直接打小寫靠自動補完 → 根本不需要 Caps Lock

然後也開始學習新的快速鍵：

• 由於更懶得離開打字區，開始學習用 ^A 和 ^E 移動游標。不過這主要是基於 macOS 的 Home / End 是控制捲軸而不是移動游標的問題。
• 發現可以用 ^N 和 ^P 上下移動游標
• 為了將來適應 MacBook Pro with Touch Bar 開始學習 ^[ = Esc（誤）

最後是開始覺得沒有方向鍵的 HHKB 似乎也可以習慣了 🤔

至於單用 MacBook 或鍵盤沒有兩鍵交換功能的時候怎麼辦呢？

有在用外接鍵盤的大概都知道，macOS 有個功能是修改鍵盤 Modifier Keys 的對應，在那裡把 Control 跟 Caps Lock 對調就行了。這樣做的話，一樣可以達到保養左手小指的效果。

用 Windows 的話，這個問題可能會更加困擾，因為 Windows 大部分的快速鍵都是 Control 按出來的。不過我自己沒在用 Windows，實際上不知道該怎麼處理。

Read more:

• Caps lock § Caps Lock versus Control key

不過遇到了一個忘記處理的問題：原本的網站會自動把文章網址從 / 轉到 /posts/，但是我忘記處理了，導致 Google Webmaster Tool 裡面噴一堆 404。

既然是 S3 轉址，我就回去看了之前的筆記，從 Webmaster Tool 把 404 列表下載回來之後，拼湊成轉址表，結果 S3 告訴我最多只能有 50 條規則，行不通了。

不過爬了一下文件才發現還有一個轉址規則是 ReplaceKeyPrefixWith，簡單來說就是幫你 replace matched path prefix，官方的範例是你要把全站的網址從 /docs 搬到 /documents 那麼就是這樣設定：

  <RoutingRules>
    <RoutingRule>
    <Condition>
      <KeyPrefixEquals>docs/</KeyPrefixEquals>
    </Condition>
    <Redirect>
      <ReplaceKeyPrefixWith>documents/</ReplaceKeyPrefixWith>
    </Redirect>
    </RoutingRule>
  </RoutingRules>

如此就有 301 轉址了。

但是要注意的是這個轉址是在 S3 設定的，所以如果前面有掛自訂 domain name 的 CDN 例如 CloudFront，那麼就要另外加上 HostName 設定才會跑到正確的網址。

所以我的 blog 是這樣設定的：

<?xml version="1.0"?>
<RoutingRules>
  <RoutingRule>
    <Condition>
      <KeyPrefixEquals>2007/</KeyPrefixEquals>
    </Condition>
    <Redirect>
      <HostName>blog.yorkxin.org</HostName>
      <ReplaceKeyPrefixWith>posts/2007/</ReplaceKeyPrefixWith>
    </Redirect>
  </RoutingRule>
  <RoutingRule>
    <Condition>
      <KeyPrefixEquals>2008/</KeyPrefixEquals>
    </Condition>
    <Redirect>
      <HostName>blog.yorkxin.org</HostName>
      <ReplaceKeyPrefixWith>posts/2008/</ReplaceKeyPrefixWith>
    </Redirect>
  </RoutingRule>
  <RoutingRule>
    <Condition>
      <KeyPrefixEquals>2009/</KeyPrefixEquals>
    </Condition>
    <Redirect>
      <HostName>blog.yorkxin.org</HostName>
      <ReplaceKeyPrefixWith>posts/2009/</ReplaceKeyPrefixWith>
    </Redirect>
  </RoutingRule>
  <RoutingRule>
    <Condition>
      <KeyPrefixEquals>2010/</KeyPrefixEquals>
    </Condition>
    <Redirect>
      <HostName>blog.yorkxin.org</HostName>
      <ReplaceKeyPrefixWith>posts/2010/</ReplaceKeyPrefixWith>
    </Redirect>
  </RoutingRule>
  <RoutingRule>
    <Condition>
      <KeyPrefixEquals>2011/</KeyPrefixEquals>
    </Condition>
    <Redirect>
      <HostName>blog.yorkxin.org</HostName>
      <ReplaceKeyPrefixWith>posts/2011/</ReplaceKeyPrefixWith>
    </Redirect>
  </RoutingRule>
  <RoutingRule>
    <Condition>
      <KeyPrefixEquals>2012/</KeyPrefixEquals>
    </Condition>
    <Redirect>
      <HostName>blog.yorkxin.org</HostName>
      <ReplaceKeyPrefixWith>posts/2012/</ReplaceKeyPrefixWith>
    </Redirect>
  </RoutingRule>
  <RoutingRule>
    <Condition>
      <KeyPrefixEquals>2013/</KeyPrefixEquals>
    </Condition>
    <Redirect>
      <HostName>blog.yorkxin.org</HostName>
      <ReplaceKeyPrefixWith>posts/2013/</ReplaceKeyPrefixWith>
    </Redirect>
  </RoutingRule>
  <RoutingRule>
    <Condition>
      <KeyPrefixEquals>2014/</KeyPrefixEquals>
    </Condition>
    <Redirect>
      <HostName>blog.yorkxin.org</HostName>
      <ReplaceKeyPrefixWith>posts/2014/</ReplaceKeyPrefixWith>
    </Redirect>
  </RoutingRule>
</RoutingRules>

btw 我有做一個搬家程式叫做 hikkoshi，可以處理泛 Jekyll 的 blog 搬家，以及 Ghost。如果你也有搬家的需求可以用用看。

參考：

• Configure a Bucket for Website Hosting - Amazon Simple Storage Service

以下是半年來的效果：

• 用 Yu-Cheng 美國人照樣叫，發音不一定會對，他們會用英語去發音，但是初次見面的時候會當面確認。雖然還是念成 /you chain/。英語裡面沒有「ü」（ㄩ）的音，所以我也不太強求了。
• 美國人分不太清楚 cheng（ㄔㄥ）和 chen（ㄔㄣ），公司裡面有另一個 yu-chen，美國同事有時候會搞混，但是也可能是 auto complete 我在後面的緣故（？）
• 跟其他廠商聯絡的時候，會有人以為我的名字是 Yu Cheng Chuang，稱呼我的時候叫我 Yu。
• 基本上不會有人叫你的姓氏，處理 given name 就好了。

現在公司裡面是外國人的只有我用拼音名字，美國那邊的人雖然是移民後代但是都有英文名字，或是母語名但是叫得出名字。這種困擾大概只有我有而已。

本來我還有個江湖名叫做 Ya Qi（鴨七），但是考慮到這個拼音要讀正確跟 Yu Cheng 大概也是一樣的難度（會讀作 /yah khi/）。當初開帳號的時候美國主管的看法是 "as long as US staff can pronounce it"，所以就不使用了。

結論是如果你在美國公司，很在乎人家唸對你的名字，就考慮換一個名字吧，但是不一定必須是美國人的名字，江湖名好唸也可以，好比說某台灣同事就用了一個日本風格的名字，大家也很開心。

至於在台灣的公司，之前大家都叫我鴨七，出去外面行走江湖（？）也都用這個名字，也是相安無事，同事們各自喜歡被怎麼叫就怎麼叫，原則上就是名從主人而已。說實話真的沒有非要英文名字不可。

不過聽說有些台灣公司會強迫取英文名字，我真的覺得走火入魔啊。

• 畫質與音質參差不齊
• 作品數量不足
• 無法正常以大螢幕觀看

表面上，只要他們改善這些問題，便能吸引動漫迷，然而我仍然認為不夠。

在說明為什麼我有這種感覺之前，先說明動漫迷怎麼觀賞日本動畫的。

動漫迷的「追番」

電視動畫（テレビアニメ）是日本重要的娛樂產業，與一般大眾認知的卡通不一樣，動漫迷所稱的動畫是指日本的深夜電視動畫，這種動畫的目標族群並非兒童，而是青少年乃至於成年人，主題廣泛，包括科幻、懸疑、奇幻冒險等等，當然也有輕鬆的後宮、戀愛喜劇等等。每一季（三個月）會有至少 30 部在日本的電視播放，其中賣座的大概也是十幾、二十部左右。不過因為作品數量多，短短 1 年，累積起來的「口耳相傳的佳作」就有 30 部以上，傳頌五年、十年的好作品也所在多有。

當然，這麼多作品不可能每個人都是每部看的，我將動漫迷看動畫的方式粗略分為三類：

• 重度追新番 - 每季都追一堆新番，幾乎是日本播完隔天就看，這樣才能跟上朋友的話題。
• 輕度追新番 - 每季追新番，但只挑評價好的，等人家評測文出來才決定要看哪些。有的人會在一季播完之後再一次看完。
• 補舊番 - 往回看舊的作品，當然是評價好的才會去看。不要說《新世紀福音戰士》這麼久的，光是 2009 年的《科學超電磁砲》現在就還有人會去追。

這三種觀賞的方式，分別需要三種不同的策略來滿足：

• 重度追新番 - 上架要快，比盜版快就贏了。國外的正版平台甚至有一小時後上架的策略。
• 輕度追新番 - 作品要足，至少熱門一點的不要漏掉，上架也不要落後超過兩週。
• 補舊番 - 也是作品要多，熱門到四、五年的盡量留在架上，並且盡可能提供 HD。

動漫需要專屬的平台

綜觀目前的情況，多數動漫迷會在網路上找盜版，不論是新番還是舊番，原因有這些：

• 正版新番同步太慢 - 正版可以慢到兩週，盜版大概一天之內就會出現翻譯版
• 正版畫質太差 - 盜版畫質其實也不算好，但目前還是有正版平台畫質低於盜版
• 設備不支援 - iPad 不是人人都有，MOD 不是家家可裝、能不能裝的控制權不見得在你手上

也因此「用電腦上網抓盜版看動畫」甚至比上網點隨選視訊還好、還快、還方便。

一個好的動漫迷專屬平台，至少要有這些：

• 作品要多 - 找不到就會去找盜版了。而且動漫迷真的會去爬五年前的舊作品來看。舊作上架後最好不要下架。
• 同步要快 - 比盜版快就贏了，盜版會差到一天，正版最好即時到一小時。
• 畫質要好 - 要有 HD，要比盜版好，不要糊，要可以用大螢幕觀看，而非小小的平板
• 月租便宜 - 一個月 $150 ~ $200 是國際趨勢，只要品質好，我甚至 300 都可以接受

還有一些不應該發生的問題：

• 音質要正常 - 128kbps 是一般人可以接受的底線；事實上我對於現在還有人壓低音質感到不可思議，要知道動漫迷之中可是有很多人對音質很講究的
• 上架時間要久 - 不要讓人有「怕它會下架」的恐懼

以上的需求，在 2014 年的今天，台灣仍沒有一個網路影音平台可以符合的。

簡單來說，如果你問一個動漫迷，家裡沒裝 MOD 想看《進擊的巨人》可以去哪裡看？人家會推薦你的服務，而不是什麼電視頻道，或是盜版平台，那就成功了。而目前，台灣仍然沒有一個平台值得推薦的。

「隱私」是中華電信 MOD 的致命傷

前一篇文章我一直捧中華電信的 MOD，但其實這種機上盒服務，有一個很大的問題，就是「隱私」。

一般來說，MOD 是接在家庭的電視機，這種配置就無法滿足動漫迷。

要知道，電視機通常是擺在客廳的，闔家觀看的作品當然可以在客廳看，但近年來熱門的動畫都或多或少有色色的畫面，比較敏感的家庭會對於這種作品很感冒，所謂「需要恥力」就是在說這種情況。而電腦螢幕是私人佔有的，自然不會這種煩惱。這類作品可以說是近年來熱門動畫的大宗，一般戀愛喜劇（ラブコメ）都有這種情節。若要滿足動漫迷而不考慮這些因素，那是非常困難的。

說了這麼多，世界上真的有這種夢幻平台嗎？答案是有的。

Crunchyroll - 真正專為動漫打造的平台

在美國，Crunchyroll 是最大的日本動畫平台，每一季都會進大量的新番同步，並且是在日本播出一小時後就上架，還附英文、西班牙文字幕。日本播出時是深夜，在美國西岸就已經是早上八、九點了，剛好可以搶先看。

它的 Player 簡單好用、也有 1080p 高畫質。Premium 會員收費則是每個月 $7 美金，折台幣大概 $210，怎麼算都很便宜。此外還有免費會員，是比 Premium 會員晚一週看到新番，並且會有廣告。

它有真正意義上的跨平台，別說 Apple Device / Windows，就連 PS4 都有支援。

雖然大部份的作品在台灣無法打開，但還是有極少數是全球授權的。2014 秋季的話，就是《Terra Formars》和《旦那が何を言っているかわからない件》。未登入會員可以試看 3 分鐘，試過一次你就知道什麼叫真正好用的網路影音平台。

不只是上架快，它還有「加入待看列表」、「評論」等功能，不只可以追番還可以吐槽，可以說是完全以動漫迷為中心來打造的平台。

並且，快速同步是真正可以有效打擊盜版的，根據 2012 年在 Tokyo Anime Fair 的演講，《火影忍者》新番同步使得盜版下載量減少 70%。

至於怎麼樣可以做到一小時同步的？根據一則 2009 年的專訪，在 4 到 8 天前就會從版權主那邊拿到腳本及畫面，著手翻譯。影片本身則沒有提到什麼時候取得，但相信只要有了翻譯，要上字幕、轉檔上架也是很快的事，而這正是字幕組辦不到的事。

Crunchyroll 的共同創辦人 Kun Gao 曾經在 Reddit 開過 AMA，有興趣的話可以去上面爬爬看。

附帶一提，創辦人是 U.C. Berkeley 出身的，果然矽谷出好產品啊…

除了 Crunchyroll 之外還有 Funimation，也是強調新番同步，跟 Crunchyroll 的作品不太有重疊，強檔舊番也很多。這家好像還有兼 BD / DVD 代理進口。

但無論如何，這兩個網站都同時符合上述的所有「專為動漫迷打造的平台」的需求。

DAISUKI：神秘的官方色彩的平台

DAISUKI 這個平台很神奇，似乎是日本的動畫發行商共同營運的網站。作品很少，但一樣是當日同步，720p HD，附英文字幕。台灣看得到的，主要是台灣還沒代理的，如《Aldnoah/Zero》、《女神異聞錄 4 黃金版》、《M3〜ソノ黒キ鋼〜》（有中文字幕），但竟然有台灣已經有代理版權的《刀劍神域 II》，更早之前還有《魔法少女小圓》，但日前已公告因為授權到期而全站下架。

中國的正版動畫平台

一般人會以為中國的網路影音都是盜版的，但實際上，最近兩年來中國政府很積極在把盜版網站轉正，目前在中國大陸，實際上是可以看到正版新番同步的。有在同步新番的網站非常多，如樂視網、百度愛奇藝（合併 PPS）、PPTV、優酷土豆網、騰迅視頻、搜狐等，最近甚至連 bilibili 也買了 Fate/stay night (2014) 的版權來播。通常都是買獨播權，也因此每季都會有版權戰爭。對岸有個網站「次元碉堡 ACGDB」專門在搜集這類的資訊。

但畫質我就沒辦法驗證了，因為台灣這裡看不到，而且就算翻牆過去，也會受限於網路速度而無法確認品質如何。

有趣的是，版權的來源，有些是跟台灣的代理商在中國大陸的分公司買的，多數的情況下，同一個作品，會同時有台灣、香港和中國大陸的版權代理，例如木棉花上海、曼迪香港（有中國大陸業務），授權的作品都跟台灣非常接近。先前中國發生過《中二病也要談戀愛！戀》在中國的搜狐視頻不慎偷跑提前播出，使得代理商暫時被日本方面取消版權，進而影響到 2014 年初的台北漫畫博覽會，該作品的所有周邊商品都臨時停售，便可以佐證版權代理是同時在兩岸三地之間運作的。

不過，雖然說有新番連載，但先前又傳出中國政府要限制境外節目都必須先審後播，新番從物理上就是不可能先審後播的，對於日本動畫在中國播出應該是會有一定的影響，但具體怎麼影響還要再看下去。

結論：Shut up and take my money!

「Shut up and take my money!」的意思是「錢拿去，我很滿意你的服務」，常用來稱讚一個服務很棒，使用者甘願付錢的情況。今天仍沒有一個真正可以讓我說出這句話的平台出現，我非常失望。

我認為最大的問題在於，目前營運的平台中，沒有一家是真正從動漫迷的需求出發的。MOD 以傳統電影租借的方式來提供娛樂戲劇的服務，是水火不容。KLand 以內容來說可以算是有，但卻往行動設備發展，這方向便是與傳統動漫迷的需求相違。myVideo 和 HiChannel 技術落後，有內容而沒有品質。台灣真正需要的是像 Crunchyroll 這樣的平台，而不只是用現有的平台來提供服務。

在音樂界我們已經有 KKBOX，一個月 $150 就可以無限暢聽，以 KKBOX 的說法就是「自來水般的服務」。對動漫迷來說，動畫的確也像是自來水一般，而目前在台灣卻仍沒有真正為動漫迷打造的平台。

Update: 完稿後，有朋友傳了一個巴哈姆特的問卷，是問若有動漫月租型服務，你願意付多少錢。這麼說，又有新的平台要出現了嗎？非常期待。

p.s. 我知道不只日本動畫在台灣有嚴重的盜版問題，美劇、日劇，甚至漫畫都有一樣的問題，不過我只看動畫，剩下的就歡迎大家發表。

一般來說，動漫迷取得動畫的管道主要都是盜版網站，iTunes App Store 和 Google Play Store 上面也一大堆盜版平台，而且一直位居排行榜的前面。但我做為一個社會人士，既有工作（所以知道任何東西都有代價），又有經濟基礎，自然認同為娛樂付出金錢是理所當然的，因此，近一年來我一直在找尋正版動畫的管道。

而事實上，台灣也的確有正版管道，但我仍然感到不滿意，並且深刻感到在台灣要收視日本動畫的困難。以下，先介紹目前在台灣有的正版管道，接著提出為什麼不滿意，以及我認為應該怎麼解。

台灣有進口正版動畫，主要的版權代理商是木棉花、群英社、曼迪、普威爾、台灣角川（近年開始）。每一季都會引進約三到五部動畫，在動漫博覽會都可以看到他們的身影。

不過版權代理商辦得到的只有版權代理和翻譯，至於播放則要靠電腦技術，目前（2014 末）可以看到日本電視動畫的台灣本土平台有這些：

MOD 是目前花錢可以買到最好的，但考慮到價錢的話，CP 值就不算高。以作品量來說，MOD 雖然上架期間短，但代理商卻是最齊全的。KLand 作品數量還算多，但只發展行動裝置，而且音質很差，目前還不支援電腦版，只有木棉花和群英社的作品。myVideo、HiChannel 作品數量比 KLand 多一些，但操作非常痛苦，號稱 HD 畫質卻只有 DVD 甚至更低。

以上四個平台都有動畫吃到飽的服務，都是最近一年才開始出現的，價錢差不多都在每月 $100 ~ $200 之間。

此外，從這四個平台可以觀察到，木棉花和群英社是最積極在網路平台上架的代理商，除了新番同步之外還會上 HD 畫質的舊番，尤其木棉花，在上述四個平台都有。曼迪則看起來很保守，以前曾經上架過「動漫集」（見文末），但目前只有在 MOD 上架，而且不見得有 HD；但也有自己的頻道播新番。曼迪、角川似乎都只在 MOD 上架，其他平台則沒有。普威爾則是還有在 myVideo 上架一些作品，目前看到的不是很多。

以下大概介紹一下各平台我用起來的心得。

中華電信 MOD

中華電信 MOD 最近開始推動漫館 $199 吃到飽，因為此我自己也訂了。以前我是沒考慮裝 MOD 的，因為很少在看一般的電視頻道，又以前 MOD 的隨選動畫是要隨選計費的，單點一次節目是綁 2 集或 3 集，要價 50 元，以一套動畫通常 12 集，有些大作 24 集，這種價格是非常昂貴的。所以動漫 $199 吃到飽對我來說誘因非常大，因此訂了。

優點：高品質、頻道即時同步

MOD 隨選視訊的優點是：

• 1080i HD，畫質與音質普遍優於盜版。
• 有新番同步，不過不一定很即時，通常在一週或兩週內。
• 一個月只要 $199，綁某些專案甚至只要 $149，非常便宜。
• 翻譯品質不在話下，不會有看不懂的大陸用語。不過這應該是基本要求。

新番若有同步上架，通常在一週到兩週後會上架，舊番的話，近三年的作品多數有 HD，舊一點的就只有 SD，好比說《科學超電磁砲》第一季 (2009) 就只有 SD，第二季《科學超電磁砲 S》 (2013) 就有 HD。不過雖然說是 SD，也是有直接看 DVD 的品質，沒有盜版那種一放大就糊得亂七八糟的問題，離螢幕遠一點倒是會有一種畫質比盜版好的錯覺，不知道為什麼突然就可以接受了。

除了隨選之外，還有三個代理商自己開設的頻道：

• 木棉花的頻道「i-Fun 動漫台」
• 群英社的頻道「My 101」
• 曼迪的頻道「曼迪日本台」

播放的內容主要是該代理商新購入的日本同步作品，以及拿自家有版權的舊作品來播。同步的作品會有實時播放，例如《刀劍神域 II》、《Fate/stay night [UBW]》(2014) 就是與日本同日即時同步的。畫質方面跟隨選差不多，但音質就不一定了，曼迪的頻道會特別把人聲強化，使得整個聲音變得很詭異。

畫質的話，只要是 HD 就是非常完美，沒得挑剔，從來沒看過在盜版會出現的壓縮馬賽克現象。根據我自己發明的明體字幕檢查法，大部份都是 1080i 的 FullHD。

內容方面也很尊重原作。隨選視訊有些比較煽情的畫面也不打碼，在頻道播出時甚至會強調「一刀未剪」，也會為此調整播出時段，但還是有像《進擊的巨人》血腥畫面打霧的情況就是了。僅管如此，還是看得出來代理商很努力在尊重原作與滿足觀眾之間取得平衡。

缺點：昂貴、不正常的上下架機制

但說到價錢，事實上除了頻道訂購費之外，還要再加上光世代專線，每個月要付出將近 $500 元。雖然以我的收入用來支付這筆錢並不會痛，但考慮到它的缺點，並沒有物超所值的感覺：

上架期間很短，約半年會下架。給我一種「趕著把它看完」的焦慮感。我認為這是因為系統原本是設計給電影用的，遇到動漫這種「會去追舊作品」的觀眾反而無法適應。此外，聽說還有「因為中華電信的容量不足，所以代理商沒辦法上架」這種情況，總覺得很莫名其妙。

舊番上架很慢。有的作品雖然已經是一兩年前的作品了，要上架到隨選的時候，還是會一週一集慢慢上。一般來說追舊番都是一口氣看完的，很少人會當新番在追的。

新番同步很慢。即使有頻道會同步首播，還是大約一週至兩週後才會在隨選上架。以網路時代的速度，三天就算慢了，何況是一週。中國和美國的正版新番同步是當日同步的，日本播完後一、兩個小時就上架，

品質良莠不齊。我在 MOD 平台看了四到五部動畫，包括頻道，部份舊動畫只有 SD，甚至有 2013 的動畫仍是 SD 的情況（這種現象以曼迪為主）。音質問題的話，目前遇到的就有爆音和異常的環境效果音（主要是木棉花和角川），或是特別 tune 過強化人聲導致聲音不對勁（曼迪的頻道）的問題。群英社和普威爾的隨選則是一向品質很好，而且字幕字體好讀，值得稱讚。

此外還有小問題，像是早期上架的影片通常都是一片綁 2 集或 3 集，如果你跟我一樣是習慣一天看一集的，遇到這種就很困擾了，因為租期是一日，若第一集看完了按暫停，隔天不在期滿之前再重新按播放，則觀看記錄會消失，在系統上會認定你重新租一次（不會另外加錢），要用快轉才能看到下一集。不過，最近上架的好像都偏向一片 1 集，所以這種問題會比較少。

又，因為 MOD 開始推「動漫館」、「戲劇館」、「電影館」這種吃到飽服務，變成如果你沒有訂吃到飽就沒辦法點進裡面的任何一個隨選，這其實是開倒車，因為 MOD 一開始就是隨選隨看、單集計價的，我如果只訂動漫館，即使我願意付單集的錢，也沒辦法看《新世紀福爾摩斯》，因為它被歸在戲劇館裡面。

結論：敢砸錢的話，MOD 是目前花錢可以買到最好的

不得不說 MOD 雖然貴，但要攻頂的話就是這個了，沒得選。雖然下架聽起來很不爽，但其實也還蠻多作品的，考慮到一批作品下架之後還會再上另一批作品，也就沒什麼了，自己安排補舊番行程便是。若不知道要看什麼，也可以看頻道的節目。

KLand 動畫

KLand 動畫 的營運公司是春水堂科技，若你的網齡有 10 年以上，應該會記得 2000 年左右曾經紅極一時的台灣原創卡通「阿貴」，沒錯，就是這家公司。我不知道為什麼這家公司開始做日本動畫平台，但總之就是有這麼一個平台。

優點：總之很便宜，行動裝置專用，有新番同步

基本上就是用手機或平板打開，然後裡面有一堆動畫，你可以點開來看，30 天只要 $89 元，非常非常便宜。它有一些是第一話免費的，不必加入會員就能看，可以試試。

除了有新番同步之外，也有舊番可以追，但目前是以木棉花和群英社為主。同步的速度的話，因為我不是每週追的那種人，所以不確定有多快，但以 2014 新番同步的節目來看，應該是一週左右。

缺點：作品量受限、品質差

但考慮到它的缺點，我不認為它有物超所值：

音質很差。直接用手機或平板的內建喇叭聽不太出來，但是一接上耳機就可以聽出它的音質奇差無比，就是壓縮過頭的那種。這是我不能忍受的一點。反應了好幾次都還是這樣子。

沒有電腦版。所以想用大螢幕爽爽看也沒辦法。此外，iOS 版本據說是可以串流到 Apple TV 的，但我手邊沒有 Apple TV 所以也沒得試。

只有木棉花和群英社。這大概只能覆蓋 40% ~ 50% 的作品，剩下的在上面則沒有。

其他的小問題像是 Login 方式不安全（要你輸入 Facebook 帳密，這在我這種 Web 技術人員的眼裡是很匪夷所思的）、選第幾話的 UI 很難用之類的。

結論：很便宜，但就是便宜價錢的那個等級，沒辦法推薦

適合在手機或平板上看，而且如果你不在意音質，只用手機或平板的內建喇叭，那麼很適合你。

但對我這種就是要大螢幕爽爽看的人，是沒辦法接受的。

myVideo

myVideo 是台灣大哥大推出的影音平台，看起來是要跟 HiChannel 競爭的，但操作界面也就只有 HiChannel 那種檔次而已。

優點：不斷充實作品，價格便宜

myVideo 也有推月租制，一個月 $150，現在推廣價是 $99，還蠻便宜的。新番跟播的作品還算多，當然這是以國內有代理的為準，至少 2014 秋番《Selector spread WIXOSS》在中華電信 MOD 隨選是沒有的（MOD 的木棉花頻道有當週同步，KLand 也有上架）。舊番的話，一眼望過去，大概就是木棉花為主，有一些普威爾的，還沒有看到群英社的。

缺點：品質低劣、UI 難用

聽起來不錯，但為什麼不推薦呢？問題主要都是在技術問題。

電腦版的撥放器很爛。為了 DRM，使用了 Silverlight，效能很差。不是說 Sliverlight 效能就不好，而是它的播放器要開始播必須等超過 30 秒，整個瀏覽器就停在那邊，就為了那個 DRM 授權。

畫質不穩。它的情況是這樣：一打開會先是很糊，然後有時候清晰，有時候又糊，有時候又中斷進入 buffering mode。不像 YouTube，你無法要求它固定在 HD，它會自動調整，但顯然自動調整很笨，用起來很不爽。我不知道是不是因為我用 HiNet 光世代所以活該連去 myVideo 很慢，但這種體驗顯然是不及格的。也就是說，即使影片標示 HD，我也從來沒有看過 HD 畫質。

嚴格限制授權的設備。我不懂為什麼要限一台電腦、一台平板、一支手機，然後一台要綁 1 個月。看起來是一種把君子當小人的心態。都還沒有人要偷你的東西就擔心別人偷你的東西。

結論：CP 值的 P 太低，不予推薦

UI 太醜、Player 太爛我都還可以忍，但我最重視的「品質」太低，因此，就算是 $150 這種價格，這種低品質的產品，我依然無法接受。

HiChannel

HiChannel 這個名字從我小時候就聽到過，算是還有點歷史（？）的平台。

優點：有新番跟播

老歸老，商業模式是有在進化，除了新番上架之外，最近還有推動漫吃到飽，但可惜是各代理商自己的吃到飽，所以如果你想全看，就得要各自買。現在到底多少錢我也不知道，我已經找不到廣告頁了。

缺點：總之就是貴，畫質很差，操作很痛苦

說它是老牌，它更像是「不思長進」的平台。整個系統的設計就是停留在我小時候的印象，完全沒有長進。

這個平台跟上述其他三個不同的是有單點計價，但很貴，一集 $25 或 $30 元，也可以買一套的，之前有看到一季 $200 元的。 不過這種方式，對於「只是想要看一下《魔法少女小圓》來稍微跟一下流行」的人來說算是還可以的價格。

至於畫質，雖然標示著 HD 但事實上畫質只有 DVD 等級。我本來以為是因為我用 Mac 才有這種問題，但我也在 Windows 確認過了，就是 DVD 等級。

UI 方面，Web 界面就是那種舊時代的土味，播放器的 Sliverlight 在 Mac 必須另外開外掛才能使用，不過 buffering 比起 myVideo 來說快太多了。

結論：老牌不死，只是駐足不前

我不知道是前公營事業都有這種情況還是怎麼樣，總之雖然商業模式一直在進步，內容也有在充實，但整個網站用起來就是土味很重，很難用，看起來也沒有想要改進。一個扶不起的平台，要我怎麼推薦。

已消失的平台

除了上述現存的平台之外，以前還有一個原壹網樂手機版變成的「NxTomo動畫館」，後改名為「動漫集」，似乎是把原壹網樂有授權的作品繼續在手機和平板上播，但最近該 App 把這些動畫全部下架了，或許是授權到期或商業政策變化也說不定。

不過它卻是開啟我動漫入門的啟蒙（？）者。2012 年底，網樂通收掉一兩個月後，我興致一來打開 iPad 的「動漫集」來看看，發現裡面有一些日本動畫，於是便開始看，做為娛樂戲劇來說我是很喜歡，而且因為是 iPad 所以畫質也不太在乎，不要讓我看到糊就好了。後來愈看愈多，便開始看盜版的 P＊S，那時候還沒有被中國政府整肅，所以其實我在上面看了不少盜版動畫。

此外還有曾經在 2013 年中在台灣實驗的「Docomo Anime Store」，原本是日本的手機看動畫服務，到了台灣變成在電腦上播放。上架的作品不算多，畫質大概是 720p HD 那個等級，不過四個月後就結束營業了，應該是來試水溫而已。

總結：沒有任何一個平台是滿意的

講到這裡，你可以知道我在意的點是什麼了：

• 畫質與音質 - 以上四個平台，除了中華電信 MOD 之外，都沒有畫質、音質可言，雖然 MOD 還是會遇到渣音質，但普遍 OK。
• 作品數量 - 上架雖然是在商言商，但有辦法網羅各家代理商的卻只有 MOD。以上架廣度而言，是木棉花 > 群英社 > 普威爾 >> 曼迪 = 角川，這樣的分佈。更別說 MOD 是有奇怪的上下架機制。
• 大螢幕觀看 - 日本電視動畫本來就是在電視上播放的，上述四平台，除了 MOD 之外，都沒辦法用大螢幕正常觀看。

表面上看來，這些平台若改善了以上缺點，便有辦法滿足動漫迷，但事實上，除了這些表面上的原因，還有更多問題是讓「動漫迷」無法滿足的。詳細請接著看下一篇。

p.s. 有一些不值得一提的平台：遠傳影城和台灣好 App。前者是看起來只是做做樣子消耗預算的，隨便上架一些然後就擺著，一如死水；後者是 App 很難用，我直接跳過了。

二七部隊，又稱台灣民主聯軍，乃台灣台中地區於二二八事件發生後，於1947年3月6日由謝雪紅、鍾逸人、蔡鐵城等多人所共同領導的反抗國民政府的武裝民兵（或稱民軍、人民軍）組織。二七部隊是二二八事件當時，規模最大、維持最久的反抗勢力組織，同時也是當時台灣民眾口耳相傳關注的焦點。

維基百科也引用了二二八紀念館的經緯，不過跟維基百科的有一點微妙的不同，兩相比較會有很明顯的感覺，所以以下主要是從二二八紀念館的紀事整理出來的。

2 月 28 日，前一天的查菸事件傳到台中之後，跟其他都市一樣，台中的民眾也聚集到警察局抗議。至此還不成組織，直到 3 月 2 日，推舉了謝雪紅做為主席舉辦市民大會，一番議論後，早上十時即出門遊行示威。在下午組成了一個叫做「台中地區時局處理委員會」的組織，並組織治安隊，但因為聽說陳儀要派兵打台中，所以治安隊就解散了。

3 月 3 日，謝雪紅將前一天解散的治安隊再度擴大，並在市參議會成立「台中地區治安委員會作戰本部」，這便是俗稱「民軍」的「人民大隊」。至 3 月 4 日，便佔領了台中市多數政府機關以及水湳的空軍飛機工廠（飛機工廠是談判到手的）。該日下午，「台中地區士紳及人民團體代表五百多名，齊集市政府禮堂，重新組織台中地區時局處理委員會」，而作戰則交由「保安委員會」來負責。惟謝雪紅不同意此決定（不願交出軍權），兩邊的意見愈來愈懸殊，謝雪紅遂在 3 月 6 日成立「二七部隊」，謝雪紅自任總指揮，由四百餘人青年、學生，以及在地的八個部隊組成，其成員甚至還有前台籍日軍。正式成軍則是在 3 月 7 日。「二七」一名是取自 2 月 27 日查菸事件。

保安委員會除設置副官團與參謀團外，還置有情報、通信、軍需、兵器、、等各部。處委會並推選吳振武擔任民軍總指揮，從而軍權乃由謝雪紅移轉至吳振武手中。惟謝雪紅不服此決定，拒絕將作戰本部的民軍編入保安委員會。保安委員會成立後，吳振武即在台中師範學校重新編組部隊，停止供應武器給中南部民軍，於是台中地區同時出現兩個步調不一的武裝系統。但保安委員會雖另組部隊，收集不少武器，但因機構過大，意見分歧，難以決定具體行動。惟謝雪紅的作戰本部仍然活躍，對各地的軍火供應亦未間斷。

── （引用自二二八紀念館網站）

是人所以會有意見分歧，「時局處理委員會」也分成保守與激進派，意見分歧，莫衷一是。3 月 8 日，一直有傳聞國民黨會派援軍，人心惶惶，「時局處理委員會」許多委員也紛紛辭職。這時候只剩下二七部隊還在作戰，根據維基百科，甚至去支援嘉義和南投的反抗軍。

3 月 9 日陳儀解散二二八事件處理委員會，以軍隊在台北肆意鎮壓。消息傳到台中，人心惶恐，終於在 3 月 11 日崩潰了，委員會開始燒燬文件，下午宣佈解散「台中地區時局處理委員會」，重新推舉原台中市長黃克立復職。台中市的一支民軍就此消滅。到了 3 月 12 日，甚至有「林獻堂、黃朝清等士紳，則在市區沿街勸募，準備製作彩坊歡迎國軍。」（嗯…）

而二七部隊考量到不要讓戰鬥波及市民，在 3 月 12 日便撤守南投埔里，並改稱「台灣民主聯軍」。半路上還派一支學生部隊去搶軍倉庫的武器和糧食，囤在埔里國民學校。之後 3 月 13 日國民黨軍隊掃盪台中，但沒有遇到二七部隊，是直到 3 月 14 日才開始在埔里發生戰鬥，稱為「埔里之戰」。戰鬥的過程可以看二二八網站的「埔里之戰」一節，或「烏牛欄之役」這則條目。總之雖然二七部隊一開始取得勝利，但最後還是敗在經驗不及正規軍隊、又缺乏彈藥，乃在 3 月 16 日深夜「埋藏武器後解散」。3 月 17 日，國民黨軍隊得知民軍解散後，便進入埔里。

這是二二八期間的一段勇猛但充滿血淚的歷史，這些反抗軍之後是什麼下場呢？雖然二二八紀念館的網站上沒有提到，但還是可以想像。有一些在二二八事件的最後一戰─烏牛欄戰役這個網站有提到。

看完之後，心裡的感覺是台中人好勇猛，民主果然還是鮮血換來的。今日的台灣頂多有太陽花學運這樣的和平抗爭，若是真的遇到當年那樣引起眾怒的事件，台灣人還站得出來嗎？

不過謝雪紅何人呢？維基百科謝雪紅的條目裡面也有寫到：

謝雪紅，原名謝阿女（1901年10月17日－1970年1月15日），台灣彰化人，日治時期的台灣共產黨（日本共產黨臺灣民族支部）創始黨員之一、中國共產黨黨員、台灣民主自治同盟首任主席，是中華人民共和國八大民主黨派的參政政治人物之一。謝雪紅後來陸續出任中共中央華東局軍政委員、中華全國婦女聯合會副主席，1954年當選全國人大台灣省代表。謝雪紅於1970年被迫害致死，病逝北京。

她被稱為是台灣社會主義革命先驅，因而被譽為台灣第一位女革命家。也是二二八事件中堅持對國民政府採取武力抵抗之台中二七部隊的參與組織者。二七部隊抵抗國民黨軍隊失敗之後，轉赴廈門，後赴香港。

也就是說這個人有共產黨的背景。

看到這裡，再加上謝雪紅一心想要領導自己的軍隊，我又覺得，要是真的給她成功的話，說不定中共就直接來台灣了。

不過，也不能說這支二七部隊就是中共的同路軍，我想應該是在當時社會氛圍之下，受到鼓動而出來武裝反抗，而剛好有共產黨背景的人士嗅到了這個良機，出來組織反抗軍，這樣而已。

此外還有另一則條目提到她：台灣民主自治同盟，這是謝雪紅在台灣反抗失敗、逃到香港之後成立的，之後在 1955 又跑到了北京。此後一直是以一個「中華人民共和國的政黨」活動著，其黨章（？）就是以統一台灣為目的的。

不過謝雪紅在文革時期也免不了落到被批鬥致死的下場就是了。

這段歷史在中學課本裡面隻字未提，至少這幾個名詞對我來說都是聞所未聞的。在 Google 上面找也大都是中國學者的研究，當然免不了帶一點政治傾向。

現任民進黨立委林佳龍，曾在 2010 年 2 月 27 日在自由時報投過一篇社論「二七部隊 台中精神」來歌頌那時代的反抗軍中的一些重要人物。

而當時已幾乎全盤控制台中市警察、營區、行政機關的二七部隊，為免台中市陷入戰火、生靈塗炭，於三月十二日毅然決定撤離台中，井然有序的轉進埔里。黃金島隊長並在烏牛欄（愛蘭橋附近），與國府軍隊展開激烈槍戰，以率領的三、四十位民兵，對抗七、八百位正規軍，雙方死傷慘重，直到彈盡援絕才棄守。

以這則社論的調調來說的話，的確當時的人們只是想要反抗國民黨而已，倒不見得是存心要以社會主義統治台灣。然而根據二二八紀念館的事紀，要說起當年民軍的故事，二七部隊應該只是其中的一部份，而不是主角。

不過林佳龍的社論裡也提到一套書叫做《辛酸六十年》，共有三本，是由當年的部隊長鐘逸人在八十九高齡時所著的書。此外還有另一本書是由當時烏牛欄戰役的第一線指揮官黃金島口述的《二二八戰士黃金島的一生》，我想我應該買來看看，畢竟我現在可以找到的資料實在太片段了，妄下結論不是什麼好事。

p.s. 以上的論點是我翻過少數幾篇網路資料之後才做出來的個人心得，若是有對您或您的家人朋友有不敬之處，此非我本意，我向您致歉，也歡迎您在留言中指正我。我並非歷史研究專業，若有不盡之處，尚祈海涵。

參考資料

• 二二八事件 - 維基百科，自由的百科全書
• 二七部隊 - 維基百科，自由的百科全書
• 二二八國家紀念館- 二二八大事記
• 烏牛欄之役 - 維基百科，自由的百科全書
• 謝雪紅 - 維基百科，自由的百科全書
• 台灣共產黨 - 維基百科，自由的百科全書
• 台灣民主自治同盟 - 維基百科，自由的百科全書
• 〈自由廣場〉「二七部隊 台中精神」 - 言論 - 自由時報電子報
• 二二八事件的最後一戰─烏牛欄戰役 | 台灣獨立建國聯盟
• 豆腐魚聽自言自語:拜訪烏牛欄戰役第一線指揮官黃金島先生 - 樂多日誌

因為最近收到回信，所以我又去研究了一下台灣的時區，這次重點是放在日光節約時間。

簡單來說，中央氣象局網站上大家常引用的，以下的這個日光節約時間的資訊，不是完全正確的。

我去翻了臺灣省政府網際網路公報查詢系統、政府公報資訊網，搜尋「夏令時」、「日光節約」、「夏季時」的公告，終於把每一年的日光節約時間的實施給湊出來了。

基本上都對，只有民國 34 到 36 年是錯的。

民國 34 年台灣光復，但 34 年實施是 5/1 至 9/30，台灣光復是 10/25，怎麼想都不可能由中華民國政府實施日光節約時間。不過其實有找到當年的電文。此外也找到了台灣總督府的告示，要在 1945 年 9 月 21 日改回西部標準時（UTC+8）。

民國 35 年實際上是從 5/15 到 9/30，有公文可證，甚至還有日譯文。

民國 36 年實際上是從 4/15 到 10/31，而且原本打算實施到 9/30，在 9/15 又決定延到 10/31。這在之前的文章寫過了。

每一年的公文整理如下。我發現到網路上很多人直接 copy 氣象局的網站，畢竟是權威機關所以相信也是理所當然的，也不能怪大家不去求證。我已經去信請氣象局更改網頁了，希望可以早日修正才是。

Update: 下表我已經整理至 Wikipedia: 夏令時間 條目了，所以你如果看到類似的表格，不用懷疑，是我做的，不是我抄他，也不是他抄我。

引用文獻

以下原始文獻都可以在政府公報資訊網、臺灣省政府網際網路公報查詢系統、臺灣總督府（官）報資料庫找到。我把它們全部搬到 Wikisource 了。

• 1945a: 國防最高委員會規定全國各地自三十四年五月一日起至九月三十日止將時間提前一小時令仰遵照並飭屬遵照由 (民國34年國民政府訓令)
• 1945b: 臺灣ノ標準時ニ關スル件 (昭和二十年台湾総督府告示第三百八十六号)
• 1946a: 電知實行夏季時間 (民國35年臺灣省行政長官公署代電)
• 1946b: 夏季時間ヲ實行スルニ付承知相成度 (1946年台湾省行政長官公署代電)
• 1947a: 電行政長官公署所屬各機關為奉令自卅六年四月十五日起實行夏令時間 (民國36年臺灣省行政長官公署代電)
• 1947b: 電府屬各機關學校為本年夏令時間奉令延長至卅六年十月卅一日午夜廿四時止 (民國36年臺灣省政府代電)
• 1948: 電府屬各機關學校為奉層令規定卅七年夏令時間自卅年五月一日零時起至九月卅日午夜廿四時止 (民國37年臺灣省政府代電)
• 1949a: 電省屬各機關學校為奉行政院電知本年夏令時間仍照成例鐘點撥早一小時 (民國38年臺灣省政府代電)
• 1949b: 電省屬各機關學校為本年夏令時間自五月一日零時起至九月卅日午後廿四時止 (民國38年臺灣省政府代電)
• 1950: 電省屬各機關學校為奉行政院令自五月一日零時起施行夏令時間 (民國39年臺灣省政府代電)
• 1951: 電省屬各機關學校為奉行政院令自五月一日零時起施行夏令時間 (民國40年臺灣省政府代電)
• 1952: 電本省所屬各機關學校為三月一日零時起全國實行日光節約時間 (民國41年臺灣省政府代電)
• 1953: 令省各機關學校為奉行政院令以四十二年度日光節約時間自四月一日零時起開始實行 (民國42年臺灣省政府令)
• 1954: 令各機關學校為奉行政院令知本年度日光節約時間 (民國43年臺灣省政府令)
• 1955: 令省屬各機關學校為奉行政院令知改訂本年度日光節約時間 (民國44年臺灣省政府令)
• 1956: 令省屬各機關學校為層奉總統令本年日光節約時間仍自四月一日零時起至九月卅日午夜廿四時止一案，令希遵照 (民國45年臺灣省政府令)
• 1957: 令省屬各級機關學校為奉行政院令知實施夏令時間一案，轉希遵照 (民國46年臺灣省政府令)
• 1958: 令省屬各級機關學校為四十七年度夏令時間自四月一日零時起實施 (民國47年臺灣省政府令)
• 1959: 令省屬各機關學校為奉令自四月一日實行夏令時間，轉希遵照 (民國48年臺灣省政府令)
• 1960: 令省屬各級機關學校、各縣市政府（局）為抄發本府暨所屬各級機關全年各月份辦公時間表及四十九年夏令時間起止日期，希遵照 (民國49年臺灣省政府令)
• 1961: 令省屬各級機關學校為五十年夏令時間自六月一日零時起至九月三十日午夜二十四時止，希遵照 (民國50年臺灣省政府令)
• 1962: 行政院令五十一年夏令時間毋須循例辦理及各機關辦公時間仍照原規定辦理案 (民國51年臺灣省政府令)
• 1974: 行政院函為節約用電實施「日光節約時間」自四月一日零時起至九月三十日二十四時止 (民國63年臺灣省政府函)
• 1975: 行政院函為節約用電實施「日光節約時間」自六十四年四月一日零時起至九月三十日二十四時止 (民國64年臺灣省政府函)
• 1976: 夏令「日光節約時間」自本年起停止實施 (民國65年臺灣省政府函)
• 1979: 函轉行政院規定節約能源實施「日光節約時間」 (民國68年臺灣省政府函)
• 1980: 函知六十九年停止實施「日光節約時間」及重新規定省屬各機關辦公時間 (民國69年臺灣省政府函)

• 在 Gem 裡面， lib/models/post.rb 定義 Post < ActiveRecord::Base
• 在 App 裡面， app/models/post.rb 打開 class Post 多寫一些 app-specific methods

然後就搞了三天搞不定。

具體的現象是：

• 在 Gem 裡面，不論是使用 Kernel#autoload 還是 Rails 的 config.autoload_paths << 來做到自動載入，都無法在 App 改寫 Post class 。
• 如果在 Gem 裡面不做 autoloading ，則 Rails 會去抓 App 裡面的 app/models/post.rb, which is not inherited from ActiveRecord::Base 。

之後試了繼承（很難搞）和 module ，最後是用 ActiveSupport::Concern 包了 module ，把 association 之類的東西寫在 included do 裡面，解決。

今天讀到這篇文章 Rails autoloading — how it works, and when it doesn't ，對於 Ruby 和 Rails 的 "autoload" 有粗略的瞭解了。簡單整理如下：

• Ruby 的 Kernel#autoload 是告訴 Ruby runtime 「要找某個 constant 的時候，可以載入某檔案」，比較像是「登記」，在登記之後， Ruby runtime 若發現程式裡面有要用某個 const ，但沒有定義，就會載入該檔案，這是發生在「第一次使用」的時候，用第二次就不會觸發。
• Rails 的 autoloading 跟 Ruby 的 Kernel#autoload 完全不一樣，實作方式是用 Module#const_missing ：抓不到（const 在 runtime 沒定義）的時候才自動根據 constant 找檔名，例如 Taiwan::Taipei::SungShan 就是會找 taiwan/taipei/sung_shan.rb 。
• 承上，「要去哪裡找檔案」這件事，是在 config.autoload_paths 設定的，這個 array 就是「要自動從檔案載入缺失的 const 的時候，就去依序搜尋哪些路徑」，類似 shell 的 $PATH 。如果檔案不存在，就會 raise NameError ；如果檔案存在，但 const name 跟所要找的不同，就會出現「Expected app/models/user.rb to define User」這種錯誤。
• 承上，第一次載入完成以後，就可以在 Runtime 裡面找到，所以不會再度觸發 const_missing 來自動搜尋。

所以：

• Kernel#autoload 不應跟 Rails 的 autoload_paths 混淆，要視為兩個完全不同的功能
• 誰第一次載入誰算數， Rails 只在找不到該 const 的時候才會去 autoload_paths 搜尋
• 所以，如果某個 const (class / module) 已經在 runtime 裡面定義了，那麼要在 Rails 裡面 reopen 它，就必須確定它一定會執行，例如 initializers 裡面，或是手動 require 它。如果是放在某個 autoload paths 裡面，例如 app/models/ ，則 Rails 並不會執行之，因為同名的 const 已經在 Runtime 裡面了。

這也就是為什麼會有「在 gem 和在 app 裡面，同名的 model class 是 mutually-exclusive，除非手動 require 才能改寫其內容」。也就是說，想要在 gem 裡面定義一個 model ，然後在 rails app 裡面 reopen 它，是不可能的，必須要手動載入它的 reopening。

說得更 general 一點就是：如果該 class / module 已經在 Gem 裡面載入，則要在 Rails 裡面 reopen 它，就必須放在 autoload_paths 以外的地方，並且手動 require 之。

該文很推薦一讀，除了詳細說明了 Ruby 和 Rails 的 autloading 機制，還提到一些陷阱，例如說 Rails 的 autoloading 其實不會理 Module.nesting (lexical context of current line) ，這樣子某些情況下會變成「第一次可以成功 autoload ，但第二次卻說 NameError 找不到 const」這種問題。

This tutorial was originally written in Chinese, so if you know Chinese please read this: OAuth 2.0 Tutorial: Grape API 整合 Doorkeeper.

To protect the API with OAuth 2, we have to build the following things:

• Resource Owner - The role who can grant authorization to the 3rd-party application, i.e. the User.
• Authorization Server - Everything about authorization goes here, such as:
  • Clients - We need a basic CRUD interface to manage clients (applications).
  • Access Token (Model) - We need a Model to store Access Tokens.
  • Authorization Endpoint - Here to process Auth Code Grant and Implicit Grant flows.
  • Token Endpoint - The Access Tokens are actually issued here.
• Resource Server - A location for applications to access, i.e. the API. Some APIs that need Access Tokens to access are called "Protected Resources."
  • Guard on Resource Server - To protect some APIs from accessing them without Access Tokens.

Most components are implemented with existing solutions:

• Resource Owner (User) - Devise
• Authorization Server (OAuth 2 Provider) - Doorkeeper
• Resource Server (API) - Grape
• Guard - Manually integrated Rack::OAuth2 into Grape.

Since doorkeeper_for from Doorkeeper can only be used in Rails, and Rack::OAuth2 is simply a Rack Middleware, so we have to mash them up manually. I've written a simple review for the current solutions: 〈Ruby / Rails 的 OAuth 2 整合方案簡單評比〉 (Chinese only; may be translated into English someday)

I've put the whole process in chitsaou/oauth2-api-sample repository. Each step has a corresponding step-x tag, for example the result of Step 1 is available at step-1 tag.

Step 1: Build Resource Owner Business Logic (User)

As mentioned above, we'll build it with Devise. This should be the basics of every Rails Developer, so I'm going to skip the details. Check out step-1 tag for the result.

You can try access /pages/secret and it should ask you to login.

Step 2: Build the Resource Server (API)

Here I'm building the API with Grape, because I don't want the request pass through too many stacks on Rails.

This is simple, and not the key part of this tutorial. If you hit any problems, just check the official document. Check out step-2 tag for the result.

Step 3: Build the Authorization Server (Provider)

It's based on Rails, so I'm going to use Doorkeeper. Check out step-3 tag for the result.

There is a video tutorial on RailsCasts which is worth checkout. However it is not that hard if we follow the official document:

Install the Doorkeeper Gem

# Gemfile
gem 'doorkeeper'

Don't forget to run bundle install.

Then run the following command to install:

$ rails generate doorkeeper:install
$ rails generate doorkeeper:migration
$ rake db:migrate

Then change the configuration file to make the Doorkeeper authenticate Resource Owner with Devise:

# config/initializers/doorkeeper.rb

# Authenticate Resource Owner with Devise
resource_owner_authenticator do
  current_user || warden.authenticate!(:scope => :user)
end

That's all. We have built a Authorization Server.

Doorkeeper creates the foolowing tables:

• oauth_applications - The registry for Clients
• oauth_access_grants - The registry of Auth Codes (issued during the first step of Authroization Code Grant Type Flow)
• oauth_access_tokens - Stores the Access Tokens that actually issued, including the corresponding Refresh Tokens (disabled by default)

Doorkeeper registers the following Routes:

The show action of Authorization Endpoint displays the grant code only, which I think is for local testing; the update actions has on actual method to catch it, not sure whether it is a dead feature or not.

You can found that:

• It gives Authorization Endpoint & Token Endpoint.
• It gives Token Debug Endpoint, which can be used to verify the Token in Implicit Flow.
• It comes with a Clients management interface.
• It also comes with a interface for users to manage authorized Clients.

Doorkeeper provides everything that an Authorization Server needs.

Step 3.1: Create a Client for Testing

After Authorization Server is built, we can now create a new Client. Open /oauth/applications/new and fill http://localhost:12345/auth/demo/callback in Redirect URI field, and submit. There does not have to be a web server on localhost:12345. We can still grab the grant code or token for testing.

Step 3.2: Get Access Token

Now we can try to get the Access Token. We're going to simulate the Client to run the Authorization Code Grant Flow. Here is how:

First, open the show page of the Client that we just created. You'll see a page displaying the Application ID, Secret and other info about the Client. At the bottom of the page, there is a Authorize link. Click it and it'll open the following location:

http://localhost:9999/oauth/authorize
    ?client_id=4a407c6a8d3c75e17a5560d0d0e4507c77b047940db6df882c86aaeac2c788d6
    &redirect_uri=http%3A%2F%2Flocalhost%3A12345%2Fauth%2Fdemo%2Fcallback
    &response_type=code

(Note: assume this Rails App runs on localhost:9999; additional line breaks are inserted for readability)

As the grant flow spec describes, the Client now sends a request to Authorization Endpoint for a Grant Code, presenting its Redirect URI and Client ID.

Now it (Doorkeeper) asks you (Resoruce Owner) whether to Authorize or Deny. We're going to select Authorize here.

It then navigates you to a location that the browser cannot open, which is the Redirect URI that we assigned when creating the app. But don't worry, we've got the Grant Code:

http://localhost:12345/auth/demo/callback
    ?code=21e1c81db4e619a23d4ed46134884104225d4189baa005220bd9b358be8b591a
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
          Grant Code

If you have noticed that during Step 3.1, the client creation page hints you to fill urn:ietf:wg:oauth:2.0:oob in Redirect URI field, and you actually did, then the grant code will be displayed in the show action. This behavior is for local testing, which is like one of Google OAuth 2.0's workflows.

Now the Client has got the Grant Code. According to the spec, the Client should exchange the Grant Code for the actual Access Token through a back channel to Authorization Server.

Because there are too many arguments to fill, here I put the screenshot of Postman. Fill the form and hit Send, then you'll get the Access Token!

Step 4: Build the Guard on Resource Server

This is the most difficult part in the tutorial. As I said in the last article (Chinese only), if the API is built with Grape, then no any Guard solution can be used immediately. If you build your API with Rails, the doorkeeper_for guard is currently not fully implemented. My current solution is taking Bearer Token middleware of Rack::OAuth2 and attach it onto Grape, and also used some logic from doorkeeper_for.

I'll detail this step as much as possible. Check out step-4 tag for the result.

The guard module is made with ActiveSupport::Concern, and put in api/concerns/api_guard.rb.

Step 4.1: Install Rack Middleware to "Fetch" Access Token (String)

When installing (use) the Rack::OAuth2 Middleware, we have to provide it a block, which will be called by the middleware. However, it will only be called if ahe request comes with an OAuth2 Token, that is:

• It calls the block if the request comes with Authorization: Bearer XXX (header) or ?access_token=xxx (query param)
• It does not call the block if the request does not have the arguments above, instead it passes to the next middleware stack （!）

Besides, this Middleware does only store the return value of block call into request.env["some key"], which means that it is used to "fetch" the Access Token, not used for checking whether the Access Token is valid and let the request complete. We have to check the validity of Access Token in the API layer.

So we install this Middleware but only use it to fetch the Access Token string:

# api/concerns/api_guard.rb
included do
  # OAuth2 Resource Server Authentication
  use Rack::OAuth2::Server::Resource::Bearer, 'The API' do |request|
    # The authenticator only fetches the raw token string

    # Must yield access token to store it in the env
    request.access_token
  end
end

Step 4.2: Make a Private Method to Take Out the Fetched Access Token (String)

I've mentioned above that the Middleware stores the Token in request.env. Actually it is stored inrequest.env[Rack::OAuth2::Server::Resource::ACCESS_TOKEN]. So let's take it out:

# api/concerns/api_guard.rb
helpers do
  private
  def get_token_string
    # The token was stored after the authenticator was invoked.
    # It could be nil. The authenticator does not check its existence.
    request.env[Rack::OAuth2::Server::Resource::ACCESS_TOKEN]
  end
end

Step 4.3: Make a Private Method to Convert Token String to Instance

Token String is simply a String, and we still have to find the actual Access Token instance in the data model. I read the logic in doorkeeper_for helper, and learned that I can invoke its AccessToken.authenticate directly, which would return an instance if found, nil if not found:

# api/concerns/api_guard.rb
  helpers do
    private
    def find_access_token(token_string)
      Doorkeeper::AccessToken.authenticate(token_string)
    end
  end

Step 4.4: Make a Service to verify Access Token

This service is built as a module called OAuth2::AccessTokenValidationService. I put it in app/services. It validates the token is not expired, not revoked, and has sufficient scopes. The "expired" and "revoked" are validated with Doorkeeper::AccessToken's built-in methods. The sufficiency of scopes validates whether the authorized scopes is equal to or more than the required scopes. The validator retruns one of the four constants defined in that module: VALID, EXPIRED, REVOKED and INSUFFICIENT_SCOPE.

I put validate_access_token helper in Grape Endpoint to make it easier to access, which directly return the result of validation, i.e. the four results mentioned above. The caller can then determine how to response according to the validation result:

# api/concerns/api_guard.rb
helpers do
  private
  def validate_access_token(access_token, scopes)
    OAuth2::AccessTokenValidationService.validate(access_token, scopes: scopes)
  end
end

The easiest way to compare scope sufficiency is set comparison: if set of authorized scopes is a superset of set of required scopes, then the scope is sufficient; otherwise it is insufficient. However if you would like to implement a logic like "Scope A includes Scope B," you should use another algorithm.

Here is the simple set comparison algorithm:

• If no scopes required, then any Access Token has sufficient scopes. Returns true.
• If there are scopes required, then compare the two set of scopes to see whether the set of authorized scopes is a superset of set of required scopes.

Ruby comes with a built-in Set datastructure so that we can do this by converting Array to Set.

# app/services/oauth2/access_token_validation_service.rb
protected
def sufficent_scope?(token, scopes)
  if scopes.blank?
    # if no any scopes required, the scopes of token is sufficient.
    return true
  else
    # If there are scopes required, then check whether
    # the set of authorized scopes is a superset of the set of required scopes
    required_scopes = Set.new(scopes)
    authorized_scopes = Set.new(token.scopes)

    return authorized_scopes >= required_scopes
  end
end

Step 4.5: Make the Guard to Deny Request without Valid Access Token

Now we're going to build the guard! method to deny API uses.

In order to make the program flow more clear, an exception for each error situation is defined. We can handle these exceptions with rescue_from in Grape, or raise Rack::OAuth2 built-in exceptions directly in those exceptions.

Here is the logic:

1. First, fetch the Token String
   • If no Token is given, it means that the Client does not know that it needs to present a token. Raise MissingTokenError.
   • According to the spec, the response should have status 401, without any detailed error message.

• If there is a Token, but but found in the database, Raise TokenNotFound.
  • According to the spec, the response should have status 401, with "Invalid Token Error."
• If the Token is found in the database, then verify it to see if it can be used to access the API: check if it is expired or revoked. If scopes are required, check the authorized scopes.
  • If the result is VALID, assign @current_user to the Resource Owner (User) bound to the Access Token.
  • Otherwise, raise respective exceptions.
  • According to the spec, if the validation failed due to insufficient scopes, the response should have status 403 with "Insufficient Scope Error," otherwise it should have 401 status code with "Invalid Token Error."

# app/api/concerns/api_guard.rb
helpers do
  def guard!(scopes: [])
    token_string = get_token_string()

    if token_string.blank?
      raise MissingTokenError

    elsif (access_token = find_access_token(token_string)).nil?
      raise TokenNotFoundError

    else
      case validate_access_token(access_token, scopes)
      when Oauth2::AccessTokenValidationService::INSUFFICIENT_SCOPE
        raise InsufficientScopeError.new(scopes)

      when Oauth2::AccessTokenValidationService::EXPIRED
        raise ExpiredError

      when Oauth2::AccessTokenValidationService::REVOKED
        raise RevokedError

      when Oauth2::AccessTokenValidationService::VALID
        @current_user = User.find(access_token.resource_owner_id)

      end
    end
  end
end

Step 4.6: Forward Exceptions to the Exceptions Built-in in Rack::OAuth2

I implemented this by capturing all the exceptons with rescue_from in Grape. You can directly raise it, too.

Notes that:

• There's a set of error_description strings in Bearer::ErrorMethods, each error code has a corresponding description string.
  • Howerver they're only filled-in automatically when the exceptions are raised from Rack authenticator with corresponding methods (e.g. insufficiet_scope!.)
  • They're not filled-in if we call the error responder middlewares directly
  • So we have to manually fill them in.
• If the error is due to not presenting a token, we can assume that Client does not know that it has to authenticate.
  • So we don't use any error code that is defined in the spec.
  • error_description can be obmitted too.
  • Respond 401 with Bearer::Unauthorized middleware.
• If the error is due to token not found, expired or revoked, use invalid_token for error code.
  • Actually we can use the same error_description string.
  • In my implementation, I raise different Exceptions and different error_descriptions for different errors.
  • You can use the same error description in your implementation, which still fulfills the requirements of spec.
  • Respond 401 with Bearer::Unauthorized middleware.
• If the error is due to insufficent scope of the token scope, use insufficient_scope for error code.
  • Respond 403 with Bearer::Forbiddden middleware.
  • However, in the implmentation of Rack::OAuth2, it does not respond with WWW-Authenticate header (actually it is only required in 401 response)
  • All error message including scope, will be found in JSON response body.
  • I've implemented a fork that fills error messages in the WWW-Authenticate header.
• My implementation does not care about error_uri and realm; the realm will be fallen back to Rack::OAuth2's default one.

# app/api/concerns/api_guard.rb
included do |base|
  install_error_responders(base)
end

# ...

module ClassMethods
  private
  def install_error_responders(base)
    error_classes = [ MissingTokenError, TokenNotFoundError,
                      ExpiredError, RevokedError, InsufficientScopeError]
    base.send :rescue_from, *error_classes, oauth2_bearer_token_error_handler
  end

  def oauth2_bearer_token_error_handler
    Proc.new {|e|
      response = case e
        when MissingTokenError
          Rack::OAuth2::Server::Resource::Bearer::Unauthorized.new

        when TokenNotFoundError
          Rack::OAuth2::Server::Resource::Bearer::Unauthorized.new(
            :invalid_token,
            "Bad Access Token.")
        # etc. etc.
        end

      response.finish
    }
  end
end

Step 4.7: Make a Guard for the whole API

This usage is copied from doorkeeper_for :all, which is used to "require OAuth 2 Token for all the endpoints under this API." For Grape, it should be implmented as a class method in Grape::API class, so I put it in ClassMethods module. Call it in Grape::API and a before filter will be inserted; all the endpoints will go through that filter.

# app/api/concerns/api_guard.rb
module ClassMethods
  def guard_all!(scopes: [])
    before do
      guard! scopes: scopes
    end
  end
end

Step 4.8: Now We Can Lock Up the API with OAuth 2

Requiring OAuth 2 on a single Endpoint:

# app/api/v1/sample_api.rb
module V1
  class SampleAPI < Base
    get "secret" do
      guard! # Requires a valid OAuth 2 Access Token to use this Endpoint
      { :secret => "only smart guys can see this ;)" }
    end
  end
end

Requiring OAuth 2 on all the endpoints under an API:

# app/api/v1/secret_api.rb
module V1
  class SecretAPI < Base
    guard_all!  # Requires a valid OAuth 2 Access Token to use all Endpoints

    get "secret1" do
      { :secret1 => "Hi, #{current_user.email}" }
    end

    get "secret2" do
      { :secret2 => "only smart guys can see this ;)" }
    end
  end
end

Try It Out!

Request to the endpoint without a valid token will be rejected:

$ curl -i http://localhost:9999/api/v1/secret/secret1.json
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="The API"
Content-Type: application/json
Cache-Control: no-cache

{"error":"unauthorized"}

If we present a valid token, it will pass, and tells me whom the user of that token is:

$ curl -i http://localhost:9999/api/v1/secret/secret1.json \
> -H "Authorization: Bearer a14bb554309df32fbb6a3bad6cba25f32a28acc931a74ead06ca904c05281b4c"
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: max-age=0, private, must-revalidate

{"secret1":"Hi, ducksteven@gmail.com"}

Step 5: Using Scope

So far, the OAuth 2 Guard supports "scopes" but the Authorization Server does not support it. How do we restrict some API endpoints must be accessed with an Access Token that was authorized with specific scopes? Here is how. For more details you can read the document of Doorkeeper: Using Scopes. Also check out the source code in step-5 tag.

First, add scope declarations in config/initializers/doorkeeper.rb:

# config/initializers/doorkeeper.rb

# Define access token scopes for your provider
# For more information go to https://github.com/applicake/doorkeeper/wiki/Using-Scopes
default_scopes  :public              # If the Client does not ask for any scopes, use these scopes
optional_scopes :top_secret,         # Other scopes that the Client can ask for
                :el, :psy, :congroo

Don't forget to restart the Rails server.

However if you open "Authorize" link, the URL does not contain scope parameter, which means "the scopes to request." So we have to modify it manually first. Add scope=top_secret parameter, like this:

http://localhost:9999/oauth/authorize
    ?client_id=4a407c6a8d3c75e17a5560d0d0e4507c77b047940db6df882c86aaeac2c788d6
    &redirect_uri=http%3A%2F%2Flocalhost%3A12345%2Fauth%2Fdemo%2Fcallback
    &response_type=code
    &scope=top_secret

It'll ask you whether to authorize or deny, again. So you know that Authorization Server understands whether you have granted the client with specific scopes in the past. After authorization, the client will get another grant code, which can be exchanged for the Access Token, for example I got 5d840a4e43049eb1e66367bc788059f9bf16b53f853f3cd4f001e51a5c95abfd this time.

Now add 2 endpoints in SampleAPI that require specific scopes to access:

get "top_secret" do
  guard! scopes: [:top_secret]
  { :top_secret => "T0P S3CR37 :p" }
end

get "choice_of_sg" do
  guard! scopes: [:el, :psy, :congroo]
  { :says => "El. Psy. Congroo." }
end

If we access top_secret endpoint with the previous Access Token, it will reject:

$ curl -i http://localhost:9999/api/v1/sample/top_secret.json \
> -H "Authorization: Bearer a14bb554309df32fbb6a3bad6cba25f32a28acc931a74ead06ca904c05281b4c"
HTTP/1.1 403 Forbidden
Content-Type: application/json
Cache-Control: no-cache

{
  "error":"insufficient_scope",
  "error_description":"The request requires higher privileges than provided by the access token.",
  "scope":"top_secret"
}

However if we use the new token, it will pass:

$ curl -i http://localhost:9999/api/v1/sample/top_secret.json \
> -H "Authorization: Bearer 5d840a4e43049eb1e66367bc788059f9bf16b53f853f3cd4f001e51a5c95abfd"
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: max-age=0, private, must-revalidate

{"top_secret":"T0P S3CR37 :p"}

If we use the new token to access choice_of_sg, it won't pass:

$ curl -i http://localhost:9999/api/v1/sample/choice_of_sg.json \
> -H "Authorization: Bearer 5d840a4e43049eb1e66367bc788059f9bf16b53f853f3cd4f001e51a5c95abfd"
HTTP/1.1 403 Forbidden
Content-Type: application/json
Cache-Control: no-cache

{
  "error":"insufficient_scope",
  "error_description":"The request requires higher privileges than provided by the access token.",
  "scope":"el psy congroo"
}

That's expected, because the scopes does not match. To access choice_of_sg endpoint, we have to get a new access token with required scopes. As mentioned before, we have to build an authorization URL:

http://localhost:9999/oauth/authorize
    ?client_id=4a407c6a8d3c75e17a5560d0d0e4507c77b047940db6df882c86aaeac2c788d6
    &redirect_uri=http%3A%2F%2Flocalhost%3A12345%2Fauth%2Fdemo%2Fcallback
    &response_type=code
    &scope=el%20psy%20congroo
             ^^^   ^^^ space

For multiple scopes, separate them with spaces %20.

This time I got a new token 0b39839282957d8f80c01901c2468ed52341707594897ec9767af392306f1e55. If I access choice_of_sg with the new token, it will pass:

curl -i http://localhost:9999/api/v1/sample/choice_of_sg.json \
-H "Authorization: Bearer 0b39839282957d8f80c01901c2468ed52341707594897ec9767af392306f1e55"
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: max-age=0, private, must-revalidate

{"says":"El. Psy. Congroo."}

Conclusion

This tutorial only demos the simplest way to build an OAuth 2 Authorization Server and OAuth 2 Bearer Token Guard to protect Grape API, from scratch. Some features / issues are not covered:

• We have to restrict "who can register new clients", for example, only admins or logged-in users can register. I think this can be done by admin_authenticator and enable_application_owner options in Doorkeeper.
• Did not demo the usage of Refresh Token.
• Doorkeeper cannot disable some grant flows.
  • I implmented this feature in my fork, and I also posted a pull request. Maybe the maintainer will merge it someday.
• Since the guard was built manually, some features in Doorkeeper are completely unused, for example:
  • access_token_methods option (the methods which the client can present access tokens with.)
  • i18n configurations built-in in Doorkeeper.
• The guard does not use the same "realm" parameter in error resopnse.
• The guard does not put parameters in WWW-Authenticate header for insufficient_scope error
  • My fork has implemented this feature, but I haven't post a pull request to the origin.
  • Although putting this header in 403 response doesn't make sense, I still feel it better to do this, since other error responses put this too.
• The scope matching is implemented with a simple set comparison, which is not useful for some cases like "A scope includes B scope."

Finally, the Guard is not packaged as a gem. I think I may make a gem someday.

機場印象

飛機降落在北京首都國際機機場的第三航廈 E 區。一下飛機，第一印象就是「高端大气上档次」（這句話要用簡體字寫比較有感覺），門面修整得非常漂亮，挑高的大廳讓人毫無壓力，萬年流行的玻璃帷幕包住整個航廈，跟桃園國際機場不是一個等級。中國政府應該是很重視門面，之後我注意到，連收費站都蓋得高端大气上档次。

入關的時候，大概是因為這裡專門停國際線班機，所以外國人的通道排得很長，中國公民的卻沒什麼人。懶得排隊，只好違背良心厚臉皮去排中國公民的通道……（其實服務人員說可以去排外國人那邊）。既然是國際線，怎麼不把中國公民的通道挪一些給外國人呢？我看到的是各一半。

入關不需要填入境卡，出境也不用填出境卡，不確定是不是台灣人才有的優待。不過這裡檢驗的人都是警察，一臉嚴肅貌，在台灣的卻是約聘公務員，且出境時的檢查也差很多，中國北京機場的海關會搜得很仔細，台灣桃園機場的安檢隨便搜，我皮夾手機沒拿出來嗶嗶嗶，安檢人員隨便掃了一下就照樣過關……。

入境的時候沒有拍到高端大气的照片，只在回程時拍了出境大廳的照片：

另外機場沒有把台灣歸類在「國內出發」裡面，我是有感到一點欣慰……。

地鐵印象

做為一個鐵道迷，會對地鐵感興趣也是理所當然。

下飛機的地方是 E 區，取行李要去 C 區，得坐電車。這時我注意到非常熟悉的車廂、非常熟悉的車內配置、非常熟悉的無人駕駛、非常熟悉的軌道、非常熟悉的膠輪特有的晃動感，找了一下，的確找到了 Bombardier 的銘板（在地板上），果然跟台北捷運文湖線一樣是龐巴迪的系統。可惜因為趕路所以沒拍到照片就是了……。

我們坐機場快線去市區轉地鐵。然而機場快線坐上去其實不像是捷運，而是像台鐵的區間車，但又沒有像區間車那樣鐵皮。機場快線會從 3 號航廈跑到 2 號航廈，再跑回市區，運行的路線是三角形。這才意識到原來 2 號航廈和 3 號航廈離這麼遠。

在北京坐地鐵，進站是需要過安檢的，跟機場安檢一樣，你必須把行李放進 X 光機，但不需要搜身就是了。這是跟台灣最大的差別，我猜測這也是為什麼進站和出站的剪票口是在不同的角落，例如下圖，只有出站，沒有進站。有一天在下午五點左右看到湧入地鐵站的人潮，個個都要過安檢，就塞住了。之後去天安門廣場，過地下道也有同樣的安檢，實在是不知道你們在怕什麼？在台灣這種會被罵成「擾民」XD 。

地鐵站設計基本上非常新潮，與台北捷運二期路網相比，有過之而無不及，去查了一下歷史，才知道在 2000 年以前，北京地鐵只有 1 號線和 2 號線，之後的路線都是申辦奧運成功之後才開始狂蓋猛蓋的，難怪除了 1 號線和 2 號線之外，風格都非常新潮。而俗稱老線的 1 號線和 2 號線，看起來就像台鐵台北地下段。聽說蔣中正當年要把台北鐵路地下化，就是因為中共在蓋北京地鐵，所以也要來蓋一個「地鐵」來證明自己不落伍，當然從現代的眼光來看根本算不上地鐵就是了。

下圖是 6 號線東大橋站：

下圖是 2 號線前門站月台，整個就是傳統鐵路的感覺：

下圖是 10 號線的月台，有整片的月台門：

很多路線都是 L 字形互相交會，此外還有兩個環線，2 號線和 10 號線，基本上分別跑二環和四環。讓我想到台北捷運也是刻意用 L 字型來做到各線之間盡量只有一次轉乘。

地鐵的電車似乎都是中國國產的，銘板都說明是中國本土的公司製造，在台灣要不是外國進口的（川崎重工、西門子）就是日本設計、台灣車輛公司製造。另外電車的隔音非常好，車外的噪音不會很大聲，噪音像是過彎時磨軌的聲音（台北捷運橘線古亭↔東門區間的巨大聲響即是）、馬達運作的聲音，都不會干擾到車廂裡面正常講話的聲音。附帶一提，北京地鐵也相當乾淨，裡面禁止飲食，我也沒看到有人違反這個規定。

車廂內的路線指示牌設計我也覺得很不錯，用燈號來表示之後會跑到哪些車站，過站的就不亮燈，並且因為中國的地鐵習慣以數字命名，所以不會像台北捷運那樣，硬是要把「往XX、OO」的轉乘指示塞進去的情況。附帶一提，它不會像台北捷運一樣，路線圖的方向與列車行走方向一致，例如在台北捷運裡，車子的前後方向是固定的，往上行的那一頭，就不會調頭往下行，所以基本上路線圖的起迄是跟列車行走方向一致，兩側門上方的路線圖是相反的圖片。然而在北京地鐵，我坐到的車，都沒有調整這個細節，也就是說左右兩側的門，用的圖是同一張，不會調整成跟列車方向一致。下圖是 4 號線的。

地鐵票價是均一價人民幣 2 元，不管你坐多遠（機場快線除外），沒有看到任何票價表，買一張儲值卡 20 元押金 + 20 元儲值，跟台北的悠遊卡一樣。（是的我買了一張）

車上的電視，訊號應該是無線數位電視（根據馬賽克停格），但輸出的螢幕用的卻是類比訊號（根據雪花），這在北京地鐵的幾條線裡面都有發現這種情況，到底是為什麼呢……？

另外在市區裡的地鐵，還有神奇的窗外廣告，這種神奇的技術我不知道怎麼辦到的，如下圖。要是在台灣沒有專利的話，我實在覺得台北捷運應該也來搞一套。

交通印象（其他）

交通高峰時段會一直塞車，有人笑稱首都北京是「首堵」，聽說還有下班時間塞兩個小時才能回到家的。地鐵也是非常塞，差不多是台北捷運藍線下班時間那麼塞。

路上的車輛會一直按喇叭，在台灣沒辦法想像，基本上就是一直叭叭叭，而且還會亂超車，非常兇。之前有個朋友說「如果聽到電話的背景音是喇叭聲，就知道對方是在中國大陸」，這下我相信了。

路舖得非常平，台北市當然沒辦法比。我想應該是北京做為首都所以投入很多資源顧門面吧，但至少有在顧門面。

有看到兩輛連結的公車，跟台中即將上路的 BRT 很神似。有看到路面電車，不是走軌道，但有電車線、集電弓。

路上看到的機車都是電動的，很少看到內燃機的，還有看到電動車專賣店。當下猜測是政府規定，果然沒錯，有人告訴我「四環以內禁騎摩托車」。不過這裡的機車大部份沒有前後燈，也不用戴安全帽，晚上就是那種會隨時冒出來的東西，真的沒問題嗎……？

四環光是一圈就要 65km ，從會場（灯市口）拉車到 After Party 的場地（中關村），走四環路還要 1 個小時，可見北京比起台北有多大……。說到北京很大，有一天從頤和園坐地鐵要到三里屯，感覺就像從淡水到台北車站再換藍線到信義區那種感覺，當然北京地鐵走的更遠。

慢車道和快車道之間會有圍籬，腳踏車基本上騎在慢車道裡面，當然也有跟台灣一樣騎到人行道上面的，但似乎是極少數。大馬路的公車走在快車道上面，候車亭也在快車道旁，而不是在人行道上，這樣應該是可以避免像台灣那樣「騎機車要閃公車亂換車道」的情況。大馬路的人行道非常寬，人行道也有圍籬圍起來，同樣的設計之前在板橋、澳門有看到。

北京也有跟台北市 YouBike 一樣的公共自行車。

地攤在北京是真正的舖在路邊地上的攤子，都是坐在地上賣的，名符其實的「擺地攤」。

沒看到台灣那種騎樓，我猜是因為北京很少下雨，所以不需要騎樓這種設施。台灣的騎樓還兼俱人行道的功能，不過其實也都佔滿機車和攤販，想躲雨也沒得躲、想走路也要閃來閃去啊。

計程車很便宜。夜間的計程車，駕駛座會有擋板和防護罩，看來治安不太好啊。

另外路上常常見到垃圾以及很厚的沙塵……。

空氣污染印象

一直聽說北京空氣不好，出發前我還很怕我的鼻子會過敏，不過到那邊才發現完全考慮錯方向，北京空氣差是「很多粉塵」，而且很乾燥，每天鼻屎都很厚而且還會流血，指甲與肉銜接的地方一直脫皮，臉和嘴唇也一直是乾燥脫皮的。

粉塵嚴重到什麼程度呢？在台灣冬天的早晨會有霧，能見度不高，太陽出來的時候就會散開，但在北京，粉塵嚴重到全天都是霧霧的能見度，連對街的交通號誌都看不清楚，路邊停的車子個個都積上一層灰塵。我直到這時才真正體會到北京的空氣污染有多嚴重。不過離開北京的當天，空氣倒是很清新。下圖的顆粒不是因為 ISO 太高，我想表達的是粉塵很多，右邊路邊的車輛也是積了一層灰。

十月底的北京倒不至於寒冷，沒有台北冷氣團來襲時那麼冷，因為北京是乾冷，台北是溼冷。白天沒那麼冷，所以我的穿法是在台灣的秋裝，裡面穿衛生衣，加上一件很厚的羽絨外套，就可以了。相信我，因為我很怕冷。

語言印象

一直以來我都只在大陸連續劇等電視節目裡面聽到對岸的口音，這次因為去參加 RubyConf China ，所以聽到了不同的口音，即使知道對方來自深圳、上海、杭州、山東、北京，我還是不太會區分哪個是哪個。但與台灣最明顯的差異是ㄓㄔㄕㄖ（zh-, ch-, sh-, r-）聲母的翹舌音非常明顯，ㄥ（-eng）韻母的讀法也跟台灣不一樣。而北京當地的口音，最明顯的就是ㄦ（-er）尾，很多詞後面會都有ㄦ尾，比如「沒事」會說成「沒 sher」（跟事ㄦ分開不一樣，有點像是後面的ㄦ取代前面音的空韻母）。

在台灣我們稱為「國語」的普通話，其實不管怎麼練「字正腔圓」都不會像中國的普通話那樣標準，相聲演員也不像，反而眷村裡的榮民唸得還比較像。不過我要強調我並不推崇完全標準的國語或普通話，能夠溝通就行了，廣播也就算了，在日常生活這麼強調標準音，反而是一種病態。這個觀點也適用於英語。最近馬英九亂講話要新移民媽媽「不要教小孩子英語，因為會有口音」引發反彈，我想立報這篇〈誰是標準？關於新移民教小孩中文／英文／母語〉的觀點很符合我的心態。

北京當地回應「謝謝」的方法有「沒事兒」、「沒關係」、「不謝」，「沒事兒」是最常聽到的，反而台灣的「不客氣」不常聽到。

稱計程車司機為「師傅」，稱廚師也是「師傅」，叫餐廳的服務生時要用丹田的力量大聲喊「服務員ㄦ！」。附帶一提如果剛從台灣過去，可能會稱「小姐」，但實際上不可以稱女性為「小姐」，一般的場合是稱「女士」，在大陸，「小姐」指的是某種性服務。

關於繁體字，一位大陸朋友跟我說，基本上看得懂繁體字，因為沒辦法避免，一定會看到。書法家寫繁體字，招牌想要仿古也會用繁體字。招牌寫繁體字的話，政府會視為圖形，所以不強制繁體字，註冊的文字簡體就行了。遇到看不懂的，按一下翻譯程式、查個字典也就知道了，頂多是習慣一下兩岸不同的用詞（指資訊科技相關的）。有些人也喜歡繁體字超過簡體字。我想這就是馬英九所謂的「識繁書簡」吧。在台灣，因為簡體字不在日常生活使用（會寫俗體字），所以一般人很少會在生活中接觸到，在網路上比較常會接觸到。然而有些人對簡體字有排斥甚至仇恨心態，我會說只要當作不同的語言就好了，而且這個語言非常輕鬆就能學會，甚至簡體字寫成的知識比繁體字多很多（特別是資訊科技相關的），實在不需要堅持那個意識型態。

另外我覺得大陸那邊人講普通話都是用丹田在發聲，台灣人很多是用喉嚨發聲的，有些人「說話宏亮」感覺就很像他們講話的方式。

食物印象

早餐都是吃飯店的 buffet ，雖然不錯，但卻有點遠離真正北京在地的飲食習慣。

外食有吃到老北京的炸醬麵加合菜，炸醬麵本身是不錯，只是特大碗（海碗居），但老北京合菜口味卻很重。話說我還蠻喜歡豆汁的，那是一種喝起來很像酸菜湯的湯，發酵原理很類似，不過我們對於這些合菜都不太能接受。

還吃到東來順的羊肉爐，肉質很棒，只是有點騷味。後來才知道台北也有名叫東來順的涮羊肉餐廳，只是一時找不到資料（愛評網上面好像沒有），不知道是不是北京開過來的正版。

還去全聚德吃到正統的北京烤鴨，的確是鮮嫩多汁，脆皮入口即化，鴨骨熬的湯也非常棒。（有遇到天安門爆炸事件，詳下文）

還去吃海底撈火鍋，這間店很神奇，服務非常到位，不是指服務態度（這種要學很容易），而是真正貼心地知道你要什麼：

• 候位時有樸克牌和五子棋、乾果飲料給你打發時間
• 一坐定，就幫你把外套罩起來、給你圍巾，避免吸到味道
• 還發給手機用的夾鏈袋，而且套上去之後還是可以滑手機
• 還發給擦眼鏡的眼鏡布

特別好吃的東西是「滑」，相當於台灣的「漿」，例如蝦滑就是蝦漿。滑有專門的沾醬，口味有微微的辣，剛好襯托出滑的鮮味，非常棒。醬料台最大的差別是沒有「沙茶醬」這種東西（東南亞才有），有一種叫做「海鮮醬」的沾醬，味道也很棒。

有一天半夜還去了簋街（讀如「鬼街」，感謝 jjgod 指正），這個地方很神奇，到午夜還是燈火通明，有非常多的熱炒店。我們去的店是賣龍蝦的，小小隻，很好吃，但就是非常非常鹹。我們還點了皮蛋豆腐，這裡的皮蛋豆腐跟台灣不一樣，必須攪散才能吃，不然會吃到鹽巴顆粒。

北京當地的 Conf 志願者說，老北京的菜主要來自於蒙古人、回族（穆斯林）、有錢人吃剩下不想吃的食物，像是牛雜。話說回來，吃了幾間餐廳都沒有「豬肉」這種食物，只有牛肉和雞肉，甚至北京首都機場還有清真餐廳，應該可以說明穆斯林在這裡某種程度上影響了北京的飲食。

在這裡的飲用水，跟台灣一樣要去外面買瓶裝的，當地人最推薦的品牌是農夫什麼的，紅色標籤，但喝起來還是有奇怪的味道。不過很便宜就是了。

柑橘類都吃到很小顆的，大概比奇異果再小一點，跟台灣常見的蘋果大小的不同。不曉得是不是這個季節盛產。

蕃茄叫做西紅柿。百香果叫做西番蓮。土豆指的是馬鈴薯不是花生。

泡麵裡面會有叉子。

台灣馳名商標（？）也有開到北京，例如此圖的 85℃ 、鮮芋仙，還有看到 CoCo 茶飲。當然做為一個台灣人是不會在中國吃這些店的。

天安門印象

天安門廣場非常非常非常大，附近很多嚴肅的建築，像是毛主席紀念館、政府機關、與社會主義有關的建築物等等。以前看照片不覺得廣場有多大，真正去那邊才發現非常大。毛主席紀念館是其中最大的一個建築，南北的門兩側各有兩個社會主義風格的雕像，後來查維基百科，原址是北京城的大清門（民國後改叫中華門），可惜 1954 的時候被拆掉了，後來這空地用來蓋毛主席紀念館。

靠近天安門那邊有人民英雄紀念碑，上面刻的是繁體字，是中共建政不久後就立下的，然而因為被鐵鏈圍住無法進入，所以實際上是看不到上面寫什麼的，被圍起來的原因可以查一下維基百科。

天安門廣場與天安門之間有一條大馬路，叫做長安街，維基百科上面沒寫多寬，根據朋友數的結果，單側就有 7 線道。

天安門廣場南邊有兩個門，一個是正陽門，一個是前門，前門和正陽門之間有一個半圓，我猜這是當時北京城的甕城。

天安門爆炸事件

我和同行的伙伴在 10 月 28 日去逛天安門廣場，本來想再去故宮，也就是天安門，但肚子餓了就去全聚德吃烤鴨。根據照片的時間，進門吃烤鴨的時間是 11:50 。吃的時候沒有注意到外面發生了什麼事，只覺得為什麼中午人這麼少，難道是星期一的緣故嗎。

出餐廳的時候，服務員說了一句「出去往南邊走，你們現在也只能往那邊走」，指著有一群人被圍在外面的柵欄處，幾個武警守在柵欄外。出了柵欄，回頭一看，整個廣場裡面都沒有人車，外面都圍起來了。似乎是發生什麼事了？定時封閉？有活動？有大官出巡？但是問當地人也說不知道為什麼。

看起來暫時不能去故宮，一行人就只好去搭地鐵前往頤和園。在地鐵上，朋友上了 Facebook ，才知道天安門發生爆炸事件（蘋果日報），聽到這事我和我的伙伴們都驚呆了。後來更詳細的新聞是 5 死、數十人受傷。

我們閃過這一劫真是上天保佑……。

頤和園印象

頤和園很漂亮，裡面的遺跡可以讓我想像到當年做為慈禧太后後花園的風光歲月。印象最深的是仿西藏風格的建築（稱四大部洲）、超級長的長廊（而且廊上的每個圖都不一樣）、超級大的湖、寺裡的巨大佛像、稱為「智慧海」的佛殿（外面有1001個佛像的雕刻）。

一進門就會看到一個碑，上面寫著 1860 年英法聯軍燒了頤和園。而導遊在帶的時候也是先提這件事，木造的建築幾乎全毀，沒燒掉的都是石造的，再強調現在看到的是市政府近年重修的。

過程中，除了帶上慈禧太后在這裡的故事，也一直提到「被英法聯軍燒毀」。沒被燒掉的像是石橋、智慧海，但智慧海外面的 1001 尊小佛像是嵌在牆上的，頭被列強砍走，現在看到的是近代重修，重新雕上去的頭（被列強砍走是導遊說的，後來查維基百科說是文革時摧毀的）。

然而我一直被導遊混淆視聽，因為光是「被燒毀」無法解釋為什麼有這麼多老舊的木造建築（涼亭、長廊等），後來去查維基百科才，才知道慈禧太后在 1880 年代挪用海軍軍費修整出來的頤和園，這麼多木造建築應該都是在那時候興建的。

雖然沒有背景知識有點吃虧，但總的來說頤和園是很漂亮的花園，此外若對歷史有興趣的話，還可以近距離接觸這些歷史，若對歷史沒興趣，欣賞清代建築、逛逛山水也很適合，非常值得一逛。我們這次只走了 2 個小時，即使有導遊還是只能算走馬看花，沒有完全逛完，估計要一整天才行。

可惜的是沒能去看北大……聽說以前是王府。

附帶一提，凡是特別的地磚路，例如橋上正中央有一條路，那就是皇帝走的。

三里屯印象

三里屯這個行程是專門要去 Apple Store 朝聖的，因為台灣沒有直營店，要去的話只能出國順便逛。

直營店乍看之下雖然跟台灣的某些經銷商差不多，也提供無壓力的試用，特別的地方是漂亮的裝潢（包括傳說中的透明樓梯），以及 Genius Bar ，一對一的服務，這種在台灣就完全沒有了。

Apple Store 坐落在三里屯的精品商圈裡面，附近除了電影院，還有 Uniqlo 、NIKE 等精品商店，常常遇到西洋人，附近還有很多酒吧，甚至有掮客在招攬。要比喻的話，就很像台北市的信義區商圈。但最大的不同是三里屯有一堆大使館（ｒｙ

對了，這裡的 Apple 產品賣得比台灣貴，要撿便宜不能去中國。Uniqlo 的價位倒是跟台灣差不多。

Conclusion

• 北京乍看之下很華麗，但細節的地方卻不那麼美好，例如雖然有高樓大廈，但卻常常看到垃圾。地攤我倒覺得沒什麼，反而這才是都市的活力。
• 空氣很糟，不適合我常住久居。但回來台北就不覺得台北空氣很髒了。
• 旅遊景點很多，歷史控可以來看看。
• 「招攬」特別有人情味，但要小心詐騙，像是聲稱帶你去哪裡多少錢，其實不是跳表的計程車，專門坑遊客。
• 物價跟台北差不多，甚至還高一點，尤其是外國品牌特別貴，像是 Apple Store 、星巴克、漢堡王。
• 人提供的服務就非常低廉，例如計程車。
• 便利商店不便利，飲料不會放冰箱（至少我去的那間）。
• 路上很多施工，半夜也施工，挖到一半就放置不管的比比皆是。台灣至少會圍起來。
• 最神奇的奇觀是在便利商店裡面有人孔蓋。
• 安檢安檢安檢，不知道政府在怕什麼。
• 北京感覺是砸很多錢去顧門面、整市容的地方，但總比台北懶得搞、亂搞來得好。
• 遇到的人大多很和善、很健談，非常值得交朋友。不曉得是不是因為是去參加技術研討會，當然我也希望中國人都很親切。
• 吸菸很普遍，連飯店都有可吸菸樓層，訂房的時候要注意一下。
• 沒逛到書店我表示很幹。

關於上網：中華電信的話可以事先預約開通漫遊上網，我買的方案是 3 天 999，也可以落地時依照自動收到的簡訊開通。用 3G 漫遊的話不會有 GFW ，可以上 Facebook 、 Twitter 等在中國大陸被封鎖的網站。

關於證件：台灣人去中國大陸要辦台胞證，上面寫「无业人员」是旅行社故意弄的，據說這樣比較不會被海關刁難；不過同行人是寫「技术人员」或「职员」，好像也沒怎樣……。至於中華民國護照，在 check-in 飛機的時候會用到（即使是在中國），過海關不會用到。

英文版 / English Version: OAuth 2.0 Tutorial: Protect Grape API with Doorkeeper

整個實作流程會造出這些東西：

• Resource Owner - 可以授權給第三方 App 的角色，也就是 User。
• Authorization Server - 用來處理與 OAuth 2 授權有關的事務，像是：
  • Clients - 需要有 Clients (Apps) 的 CRUD 。
  • Access Token (Model) - 需要有個 Model 來儲存 Access Token 。
  • Authorization Endpoint - 這裡來處理 Auth Code Grant 和 Implicit Grant 。
  • Token Endpoint - 這裡來真正核發 Token 。
• Resource Server - 給 App 存取的地方，也就是 API ，一部份需要 Access Token 才能存取的叫做 Protected Resource 。
  • Resource Server 上面的 Guard - 用途是「保護某些 API ，必須要帶 Access Token 才能存取」，俗稱保全。

本文使用這些套件來實作：

• Resource Owner (User) - Devise
• Authorization Server (OAuth 2 Provider) - Doorkeeper
• Resource Server (API) - Grape
• Guard - 用 Rack::OAuth2 來整合 Grape

因為 Doorkeeper 的 doorkeeper_for 只能用在 Rails ，而 Guard 只是一個 Rack Middleware ，所以這裡要自己拼湊。詳情請見先前的文章 〈Ruby / Rails 的 OAuth 2 整合方案簡單評比〉。

所有過程我都會放在 chitsaou/oauth2-api-sample 這個 repository ，各 step 有對應的 step-x tag ，例如 Step 1 完成的結果可以在 step-1 這個 tag 看到。

Step 1: 造 Resource Owner 邏輯 (User)

用 Devise 做。這個應該是 Rails Developer 的基本功，所以不解釋了，請見 step-1 tag。

可以試著打開 /pages/secret ，會要求登入。

Step 2: 造 Resource Server (API)

用 Grape 是因為不想要讓 API 經過太多 Rails 的 stack。

這個不難，而且不是本文的重點，所以直接看官方文件就好了。成品可以看 step-2 tag 。

Step 3: 造 Authorization Server (Provider)

既然底是 Rails ，那麼就直接上 Doorkeeper 就好了。可以看 step-3 tag 。

RailsCasts 有 tutorial ，若有買 Pro 不妨去看看。不過其實照官方文件做也不難：

安裝 Doorkeeper Gem

# Gemfile
gem 'doorkeeper'

別忘了跑 bundle install 。

然後跑這些來安裝：

$ rails generate doorkeeper:install
$ rails generate doorkeeper:migration
$ rake db:migrate

再照他文件說的去接 Devise 來認證 Resource Owner：

# config/initializers/doorkeeper.rb

# 認證 Resource Owner 的方法，直接接 Devise
resource_owner_authenticator do
  current_user || warden.authenticate!(:scope => :user)
end

這樣就好了。

Doorkeeper 會建這些 model:

• OauthApplication - Clients 的註冊資料庫
• OauthAccessGrant - Auth Code 流程第一步產生的 Auth Grants 的資料庫
• OauthAccessToken - 真正核發出去的 Access Tokens，包含對應的 Refresh Token （預設關閉）

Doorkeeper 開的 Routes 有這些：

其中 Authorization Endpoint 的 show 只會顯示 grant code ，可能是 Local Testing 要用的；而 update 則是沒有任何 action 去接它，不確定是不是 dead feature 。

可以發現到：

• 幫你蓋好了 Authorization Endpoint 和 Token Endpoint
• 還附加 Token Debug Endpoint ，在 Implicit Flow 可以驗證 Token 的真實性。
• 還有附 Clients 管理界面
• 還可以讓 User 管理授權過的 Clients

所以一個 Authorization Server 該有的東西它都提供了。

Step 3.1: 開測試用的 Client

蓋完 Authorization Server 之後，要去開一個 Client 。可以打開 /oauth/applications ，其中 Client 的 redierct URI 填入 http://localhost:12345/auth/demo/callback ，實際上沒有跑 Web server 在 localhost:12345 也沒關係，最終目的是拿到 code 或 token。

Step 3.2: 拿取 Access Token

現在可以來試著拿 Access Token 了，我們要用人腦模擬 Client ，來跑 Authorization Code Grant 的流程。

步驟如下：

首先打開剛剛生的 Client 的 show 頁面，會看到有 Application ID 、 Secret 等資訊的頁面。最下面有一個 Authorize 的連結，點下去會打開到這個網址（假設這個 Rails App 開在 localhost:9999 ，下同）（中間斷行比較好讀）：

http://localhost:9999/oauth/authorize
    ?client_id=4a407c6a8d3c75e17a5560d0d0e4507c77b047940db6df882c86aaeac2c788d6
    &redirect_uri=http%3A%2F%2Flocalhost%3A12345%2Fauth%2Fdemo%2Fcallback
    &response_type=code

就像之前在流程文裡介紹過的，它用 GET 去 Authorization Endpoint 求 Grant Code ，附上自己的 Client ID 和 Redirection URI 。

接著會問你要 Authorize 還是 Deny ，當然選 Authorize 。

接著會跑到一個瀏覽器打不開的網址，是先前設定的 Redirection URI，不過沒關係，我們已經得到 Grant Code 了（中間斷行比較好讀）：

http://localhost:12345/auth/demo/callback
    ?code=21e1c81db4e619a23d4ed46134884104225d4189baa005220bd9b358be8b591a
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
          Grant Code

如果在 Step 3.1 照網頁上的指示填入 urn:ietf:wg:oauth:2.0:oob ，最後會出現 grant code 的 show 頁面，直接把 grant code 曬給你，這是 local 用來測試用的，類似 Google OAuth 2.0 的流程。

到這裡，Client 就拿到 Grant Code 了，依照流程，接下來是 Client 要另外從後台偷偷去 Authorization Server 把這個 Grant Code 換成 Access Token。

因為要填的資料太多了，我抓一下 Postman 的畫面，填完最後按下「Send」就會拿到 Access Token 了！

Step 4: 造 Resource Server 上的 Guard

造 Guard 這件事比較難，就像我前一篇文章說過的，在 API 是 Grape 的情況下， 沒有一個 Guard 是可以直接拿來用的 ；即使你用 Rails 做 API 好了，doorkeeper_for 現在也還只是半成品。我目前的做法是把 Rack::OAuth2 的 Bearer Token middleware 接到 Grape 上面，邏輯參考了 doorkeeper_for 的實作方式。

這裡會寫得比較仔細。可以看 step-4 tag 。

我寫成一個 module ，用 ActiveSupport::Concern 去簡化 module 化的程式，放在 api/concerns/api_guard.rb。

Step 4.1: 安裝 Rack Middleware 來抓取 Access Token (String)

Rack::OAuth2 這個 Rack Middleware 在安裝 (use) 的時候要傳一個 block ，它會去 call ，但 call 的條件是「Request 有帶 OAuth 2 Token」這樣才會 call ，意思是說：

• 如果 Request 有帶 Authorization: Bearer XXX 或 ?access_token=xxx 才會 call
• 如果 Request 不帶上述的參數，就不會 call ，直接 pass 到下一個 middleware stack （！）

而且這個 Middleware 在 call 之後其實會把 return value 直接存進 request.env["某個 key"] 裡面，意思就是說 「它只是給你 fetch access token 用的」 ，不能拿來「確認 Access Token 有效並放行 API access」，這件事要在 API 層做。

那麼就來安裝這個 Middleware 吧，但只拿來 fetch access token string ：

# api/concerns/api_guard.rb
included do
  # OAuth2 Resource Server Authentication
  use Rack::OAuth2::Server::Resource::Bearer, 'The API' do |request|
    # The authenticator only fetches the raw token string

    # Must yield access token to store it in the env
    request.access_token
  end
end

Step 4.2: 做一個 private method 來取出先前拿到的 Access Token (String)

前文提到 Middleware 會把 Token 存在 request.env 裡面，具體就是 request.env[Rack::OAuth2::Server::Resource::ACCESS_TOKEN] ，所以就把它拿出來吧。

# api/concerns/api_guard.rb
helpers do
  private
  def get_token_string
    # The token was stored after the authenticator was invoked.
    # It could be nil. The authenticator does not check its existence.
    request.env[Rack::OAuth2::Server::Resource::ACCESS_TOKEN]
  end
end

Step 4.3: 做一個 private method 來把 Token String 變成 Instance

Token String 只是單純的字串，還需要去 Database 裡面撈才能換成 Instance 。參考了 doorkeeper_for 的做法，我直接呼叫它的 AccessToken.authenticate ，撈不到會直接回 nil：

# api/concerns/api_guard.rb
helpers do
  private
  def find_access_token(token_string)
    Doorkeeper::AccessToken.authenticate(token_string)
  end
end

Step 4.4: 做一個 service 來驗證 Access Token 是否合法

OAuth2::AccessTokenValidationService 我放在 app/service 裡面，其中會驗證是否過期 (expired) 、是否被撤銷 (revoked) ，這兩個都是 Doorkeeper::AccessToken 內建的 methods。但此外還要驗證所需的 scopes 是否包含在 Access Token 的 scopes 裡面。回傳的驗證結果會是 VALID 、 EXPIRED 、 REVOKED 、 INSUFFICIENT_SCOPE 四個常數的其中一個（定義在該 module 裡面）。

在 Grape Endpoint 放一個 validate_access_token helper 來方便處理這件事，它會直接回傳結果，也就是上述四個之中的一個， caller 就可以根據驗證結果決定要怎麼回 response 。

# api/concerns/api_guard.rb
helpers do
  private
  def validate_access_token(access_token, scopes)
    OAuth2::AccessTokenValidationService.validate(access_token, scopes: scopes)
  end
end

在 Service 裡面要驗證 scopes ，我的演算法其實很簡單，就是集合比較而已；有的網站會有「A scope 包含 B scope」的設計，如果要做成這樣的話，就不能用單純的集合比較了。純集合比較的演算法是這樣：

• 如果沒有要求任何 scopes ，那其實任何 Access Token 都符合，就回 true。
• 如果有要求任何 scopes ，那麼「授權過的 scopes」就得是「所需的 scopes」的宇集，剛好 Ruby 有內建 Set 這個資料結構，把兩個 Array 都轉成 Set 就能方便比較了。

# app/services/oauth2/access_token_validation_service.rb
protected
def sufficent_scope?(token, scopes)
  if scopes.blank?
    # if no any scopes required, the scopes of token is sufficient.
    return true
  else
    # If there are scopes required, then check whether
    # the set of authorized scopes is a superset of the set of required scopes
    required_scopes = Set.new(scopes)
    authorized_scopes = Set.new(token.scopes)

    return authorized_scopes >= required_scopes
  end
end

Step 4.5: 製作 Guard 來擋住沒有合法 Access Token 的 Requests

現在要真正寫 guard! method 來擋 API use 了。

為了讓程式流程看起來更簡潔，根據不同的錯誤情況，定義了不同的 Exception ，各 Exception 要怎麼處理，則可以交由 Grape 的 rescue_from 處理（我是這樣做的），或 Exception 裡面直接 raise Rack::OAuth2 內建的 exception。

邏輯是這樣：

1. 先去抓出 Token String
   • 如果沒給 Token ，表示 Client 不知道要認證，丟 MissingTokenError
   • 照 spec 是要回 401 但是不給任何錯誤訊息

• 如果有給 Token 但是資料庫裡面找不到，丟 TokenNotFound
  • 照 spec 是要回 401 加上 Invalid Token Error
• 如果找得到 Token 則進一步驗證是否可以用來存取該 API （根據有否過期、被撤銷，如果有要求 scope 的話則再檢查 scope）
  • 若驗證結果是 VALID ，則把 @current_user 指定給該 Access Token 綁定的 Resource Owner (User)
  • 若驗證結果不是 VALID ，則丟出相對應的 Exceptions
  • 照 spec ，如果是因為 scope 不足，則是回 403 加上 Insufficient Scope Error ，其他情況則是要回 401 加上 Invalid Token Error

# app/api/concerns/api_guard.rb
helpers do
  def guard!(scopes: [])
    token_string = get_token_string()

    if token_string.blank?
      raise MissingTokenError

    elsif (access_token = find_access_token(token_string)).nil?
      raise TokenNotFoundError

    else
      case validate_access_token(access_token, scopes)
      when Oauth2::AccessTokenValidationService::INSUFFICIENT_SCOPE
        raise InsufficientScopeError.new(scopes)

      when Oauth2::AccessTokenValidationService::EXPIRED
        raise ExpiredError

      when Oauth2::AccessTokenValidationService::REVOKED
        raise RevokedError

      when Oauth2::AccessTokenValidationService::VALID
        @current_user = User.find(access_token.resource_owner_id)

      end
    end
  end
end

Step 4.6: 把 Exception 轉送到 Rack::OAuth2 內建的錯誤回應方式

我的做法是用 Grape 的 rescue_from 去接 exceptions ，當然要直接 raise 也可以就是了。

要注意的是：

• Bearer::ErrorMethods 有內建一組 error_description 的預設值，根據不同的 error code 去對應
  • 但只有在 Rack 的 authenticator 裡面使用相對應的 helper method (如 insufficiet_scope!) 才會填入
  • 直接 call 這個 middleware 則不會自動填入錯誤訊息
  • 所以必須手動填入
• 沒給 Token 要視為「Client 不知道要 Authenticate」
  • 所以 error code 不屬於 Spec 裡面定義的任何一個
  • error_description 也不需要給。
  • 使用 Bearer::Unauthorized 回 401
• Token 找不到、過期 (Expired) 、被撤銷 (Revoked) 的 error code 都是 invalid_token
  • 其實可以用同一個 error_description
  • 我的寫法會把三種情況分別丟不同的 Exception，並填入不同的 error_description
  • 你實作的時候可以用同一個，這並不會違反 spec
  • 使用 Bearer::Unauthorized 回 401
• Token 的 scope 不足會使用 insufficient_scope 的 error
  • 使用 Bearer::Forbidden 回 403
  • 可是 Rack::OAuth2 的實作並沒有填入 WWW-Authenticate header （只有 401 強制要求要填）
  • 所有的 error message （包括 scope）會出現在 JSON response body 裡面
  • 我有另外實作一個 fork ，會一併填入 WWW-Authenticate 裡面
• 這個實作沒有填入 error_uri 和 realm ，其 realm 會使用 Rack::OAuth2 內建的。

# app/api/concerns/api_guard.rb
included do |base|
  install_error_responders(base)
end

# ...

module ClassMethods
  private
  def install_error_responders(base)
    error_classes = [ MissingTokenError, TokenNotFoundError,
                      ExpiredError, RevokedError, InsufficientScopeError]
    base.send :rescue_from, *error_classes, oauth2_bearer_token_error_handler
  end

  def oauth2_bearer_token_error_handler
    Proc.new {|e|
      response = case e
        when MissingTokenError
          Rack::OAuth2::Server::Resource::Bearer::Unauthorized.new

        when TokenNotFoundError
          Rack::OAuth2::Server::Resource::Bearer::Unauthorized.new(
            :invalid_token,
            "Bad Access Token.")
        # etc. etc.
        end

      response.finish
    }
  end
end

Step 4.7: 製作用來擋全 API 的 Guard

這是仿 doorkeeper_for :all 的，用途是「這個 API 底下的所有 Endpoints 都要擋」。在 Grape 的世界裡面，它要是放在 Grape::API 裡面的 class method ，所以我寫在 ClassMethods module 裡面，一 call 就是塞 before filter 進去，它底下每個 endpoint 都會過這個 filter。

# app/api/concerns/api_guard.rb
module ClassMethods
  def guard_all!(scopes: [])
    before do
      guard! scopes: scopes
    end
  end
end

Step 4.8: 現在可以用 OAuth 2 來擋 API 了

單獨擋一個 Endpoint:

# app/api/v1/sample_api.rb
module V1
  class SampleAPI < Base
    get "secret" do
      guard! # Requires a valid OAuth 2 Access Token to use this Endpoint
      { :secret => "only smart guys can see this ;)" }
    end
  end
end

擋一個 API 底下所有 Endpoints:

# app/api/v1/secret_api.rb
module V1
  class SecretAPI < Base
    guard_all!  # Requires a valid OAuth 2 Access Token to use all Endpoints

    get "secret1" do
      { :secret1 => "Hi, #{current_user.email}" }
    end

    get "secret2" do
      { :secret2 => "only smart guys can see this ;)" }
    end
  end
end

試試看！

不帶 Token 就去打 API 會被拒絕：

$ curl -i http://localhost:9999/api/v1/secret/secret1.json
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="The API"
Content-Type: application/json
Cache-Control: no-cache

{"error":"unauthorized"}

附 Token 再去打 API 就沒問題了，並且會告訴我這個 User 是誰：

$ curl -i http://localhost:9999/api/v1/secret/secret1.json \
> -H "Authorization: Bearer a14bb554309df32fbb6a3bad6cba25f32a28acc931a74ead06ca904c05281b4c"
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: max-age=0, private, must-revalidate

{"secret1":"Hi, ducksteven@gmail.com"}

Step 5: 使用 Scope

到目前為止，實作出來的 OAuth 2 的 Guard 雖然支援「scopes」，但 Authorization Server 不支援。要怎麼限制某些 API 必須使用「授權了某些 scopes」的 Access Token 才能存取呢？以下是範例，詳細可以參考 Doorkeeper 的文件 Using Scopes 。程式碼見 step-5 tag 。

首先在 config/initializers/doorkeeper.rb 裡面增加 scopes 的定義，例如

# config/initializers/doorkeeper.rb

# Define access token scopes for your provider
# For more information go to https://github.com/applicake/doorkeeper/wiki/Using-Scopes
default_scopes  :public              # 如果 Client 不索取任何 scopes 則預設使用這組 scopes
optional_scopes :top_secret,         # 其他可以額外申請的 scopes
                :el, :psy, :congroo

要重開 Rails server 生效。

接著打開 Authorize 的頁面，點下去的網址不會帶有「想要索取的 scopes」，所以先把網址複製下來，後面手動附上 scope=top_secret 參數：（中間斷行比較好讀）

http://localhost:9999/oauth/authorize
    ?client_id=4a407c6a8d3c75e17a5560d0d0e4507c77b047940db6df882c86aaeac2c788d6
    &redirect_uri=http%3A%2F%2Flocalhost%3A12345%2Fauth%2Fdemo%2Fcallback
    &response_type=code
    &scope=top_secret

到這裡會再問你要不要 Authorize ，所以你知道了 Authorization Server 會區別帶有不同 scopes 的 grants。Authorize 之後會得到一組 grant code ，再照標準流程拿 Token 。我這次拿到的 Token 是 5d840a4e43049eb1e66367bc788059f9bf16b53f853f3cd4f001e51a5c95abfd.

現在我在 SampleAPI 裡面新增兩個 endpoint ，需要 scopes 才能存取：

get "top_secret" do
  guard! scopes: [:top_secret]
  { :top_secret => "T0P S3CR37 :p" }
end

get "choice_of_sg" do
  guard! scopes: [:el, :psy, :congroo]
  { :says => "El. Psy. Congroo." }
end

用之前申請過的 Access Token 來打 top_secret 這個 API 會被拒絕（中間斷行比較好讀）：

$ curl -i http://localhost:9999/api/v1/sample/top_secret.json \
> -H "Authorization: Bearer a14bb554309df32fbb6a3bad6cba25f32a28acc931a74ead06ca904c05281b4c"
HTTP/1.1 403 Forbidden
Content-Type: application/json
Cache-Control: no-cache

{
  "error":"insufficient_scope",
  "error_description":"The request requires higher privileges than provided by the access token.",
  "scope":"top_secret"
}

若用新拿到的 Token 就會過了：

$ curl -i http://localhost:9999/api/v1/sample/top_secret.json \
> -H "Authorization: Bearer 5d840a4e43049eb1e66367bc788059f9bf16b53f853f3cd4f001e51a5c95abfd"
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: max-age=0, private, must-revalidate

{"top_secret":"T0P S3CR37 :p"}

然而如果拿這個 Token 去打 choice_of_sg 就會被拒絕（中間斷行比較好讀）：

$ curl -i http://localhost:9999/api/v1/sample/choice_of_sg.json \
> -H "Authorization: Bearer 5d840a4e43049eb1e66367bc788059f9bf16b53f853f3cd4f001e51a5c95abfd"
HTTP/1.1 403 Forbidden
Content-Type: application/json
Cache-Control: no-cache

{
  "error":"insufficient_scope",
  "error_description":"The request requires higher privileges than provided by the access token.",
  "scope":"el psy congroo"
}

當然，因為 scope 不符啊。這時候就要再重新申請一個 Token ，照前面說過的流程，要先有一個 Authorize 的 URL:

http://localhost:9999/oauth/authorize
    ?client_id=4a407c6a8d3c75e17a5560d0d0e4507c77b047940db6df882c86aaeac2c788d6
    &redirect_uri=http%3A%2F%2Flocalhost%3A12345%2Fauth%2Fdemo%2Fcallback
    &response_type=code
    &scope=el%20psy%20congroo
             ^^^   ^^^ space

多重 scope 的情況下，各 scope 之間用空格 %20 分開。

最後我拿到的新 Token 是 0b39839282957d8f80c01901c2468ed52341707594897ec9767af392306f1e55 。再用它去打 choice_of_sg API 就會回我了：

curl -i http://localhost:9999/api/v1/sample/choice_of_sg.json \
-H "Authorization: Bearer 0b39839282957d8f80c01901c2468ed52341707594897ec9767af392306f1e55"
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: max-age=0, private, must-revalidate

{"says":"El. Psy. Congroo."}

結語

以上的 Tutorial 只簡單示範了如何從零建造一個 OAuth 2 Authorization Server 並且用 OAuth 2 Bearer Token 來保護 Grape API 。以下這些問題沒有處理：

• 要可以限制「誰才可以開 Clients」 （例如站長，或是有登入的使用者），我想應該是 Doorkeeper 的 admin_authenticator 和 enable_application_owner options 。
• 沒有示範 Refresh Token
• Doorkeeper 不能設定只要開啟哪些 Grant Flows
  • 這我有開一個 fork 出來實作，也貼了 Pull Request ，等他 merge 。
• 因為 Guard 是自己寫的，Doorkeeper 的一些功能完全不使用，例如 access_token_methods （設定 Client 可以用哪些方式向 API 出示 Token）
• 承上，也沒有使用到 Doorkeeper 內建的錯誤訊息 i18n 機制
• Guard 的 Error Response 的 "realm" 不同步
• Guard 的 insufficient_scope Error 沒有把參數放在 WWW-Authenticate header
  • 我的 fork 有實作這個，還沒開 PR 給原版。
  • 雖然在 403 放這個 header doesn't make sense ，但總覺得還是統一放在這裡比較好啊…
• Scope 的 matching 只用了簡單的集合比較，不適用於某些 A scope 吃 B scope 情況

又，寫完的 Guard 並沒有包成 Gem 還是什麼的……之後應該會包一下吧。

有任何問題（包括指教本文的謬誤）歡迎在下面的留言板提出 :)

• 造一個 Authorization Server 用來管理 Client 和 Token ，包括核發 Access Token
• 在 Resource Server （即 API） 放一個 Guard ，用來限制某些 endpoints 必須帶 OAuth 2 Access Token

因為我要造的 API 是 Grape 搭起來的，掛在 Rails 底下，於是就 survey 了一些方案：

• Doorkeeper
• Rack::OAuth2
• Warden::OAuth2
• Grape::Middleware::Auth::OAuth2 （偽）

你可能會問： OAuth2 這個 gem 呢？其實他只有實作 Client ，所以不在本文範圍（完）。

Doorkeeper

• 完整的 Authorization Server solution 。
• 簡陋的 Resource Server Guard solution
• 有內建 Client management
• For Ruby on Rails -- 如果你用 Sinatra 就不能用了。

基本上幫你搞定 Authorization Server 的所有需求，但 Resource Server Guard 則是很簡陋，或說根本是隨便寫的，只會幫你丟 401 Unauthorized ，Bearer Token 的要求他幾乎沒實作。具體程式碼在 lib/doorkeeper/helpers/filter.rb (Tag: v0.7.3) 。有人開 Pull Request 但沒有 merge： support the spec of 'invalid_token' response by masarakki 。

Rack::OAuth2

• 有 Authorization Server
• 有 Resource Server Guard ，完成度很高
• 沒有內建管理 Client 的方式
• Rack Middleware × 2 ： Authorization Endpoint 和 Token Endpoint
• View 要自己刻
• 沒有綁 Model ，自己刻。

簡單來說只幫你處理掉 Protocol 而已，支持它的 Model 和 View 必須自己處理。

Resource Server Guard 「完成度很高」是相對於 Doorkeeper 而言。

問題點：

• insufficient_scope error 沒有帶 WWW-Authenticate 和 required scopes。
• 它的 authenticator （就是 use middlware 的時候要丟進去的 block）只會在「有傳 token」的情況下才會 call，沒傳 token 就會跳過，繼續往下一個 Rack stack 跑，所以只能用來「抓 token」。
• 承上，這個 authenticator procedure 要 yield 一個 token object 用來儲存在 Rack env 裡面（raw string 或 model instance 都行），所以它真的就是拿來「抓 token」用的而已。
• 承上，真正驗證 Token 正確與否的程式要寫在 Application layer ，不能寫在 Rack middleware ，否則就會發生「沒傳 token 卻可以 access API」的問題。

Warden::OAuth2

它會跟 Devise 的 warden 卡在一起，所以我沒有深入研究。

Grape 的 OAuth 2 authorization

Source Code (master): https://github.com/intridea/grape/blob/master/lib/grape/middleware/auth/oauth2.rb

檢閱日期是 2013/10/07 ，與當下最新版本 v0.6.0 一致。

• 既然是 API Framework 提供的，當然只有 Resource Server Guard
• 但是沒做完
• 而且 它並不會 mount 這個 middleware ，所以實際上無法使用（具體見 這個 Pull Request）

既然目前的版本無法使用，只能看 code 說故事。它的問題所在：

• 要自己造 Model ，預設是 AccessToken ，並且這 class 要實作 #expired 和 #permission_for?
• #permission_for? 就是 scope 驗證，傳進去的參數是整個 Rack env （……）。
• 但 insufficiet_scope 的 response 並不會提示 required scopes （同 Rack::OAuth2）
• 完全沒有 error_description
• Auth-Scheme 同時吃 Bearer 和 OAuth2 ，第二種不是 spec 規定的，顯然不需要

我的做法: Doorkeeper + Rack::OAuth2

以上每個 solution 都不完美，就只好自己搭了。

我的做法是這樣：

• Doorkeepr 拿來蓋 Authorization Server ，一鍵搞定
• API 是用 Grape 蓋起來的，所以不用（不能用） Doorkeeper 的 doorkeeper_for。
• Guard 改用 Rack::OAuth 2 ，自己寫一個 module 給 Grape 來處理兩邊的整合

之後會寫一篇 Tutorial ……最近幾天內會發表。

Edit: 寫完了： OAuth 2.0 Tutorial: Grape API 整合 Doorkeeper

且就算 realm 不同，瀏覽器都會試同樣一組帳號密碼，我試過用 Sinatra 做一個微 App ，分別有以下的 routes：

這樣子的話：

1. 先登入 a1 ，再去 b （不同的 realm）則瀏覽器會用 a2 用過的密碼試著去登入 b。

• 先登入 a1 ，再登入 a2 ，再去 a1 （同樣的 realm）則瀏覽器會用 a2 用過的密碼試著去登入 a1。

我在 Safari, Chrome, Firefox 都試出一樣的行為。從結果來看應該是不能從 realm 去劃分區域，並且預期瀏覽器會認 realm 來決定要用哪一組帳號密碼，甚至瀏覽器會把上一次用的 realm 記起來，忘掉之前用過的，再遇到同一個 host 裡面需要 authenticate 的場合，就用新的帳密。所以作用域是 per-host 嗎？

如果說 OAuth 2 的 realm 跟 HTTP Basic Auth 的 realm 一樣，那是否表示 realm 是給人類看的，而不是給程式看的呢？我不確定。求科普。在 StackOverflow 上面有人說「Realm 一樣的，就會用同一組帳密」，但從結果來看不是這樣。

然而，即使 OAuth 2.0 的 spec 規定了很多通訊協定上的實作細節，但現實總是跟理想有所差距，各大網站的 OAuth 2 實作都或多或少與 spec 有差異，真正完全照 spec 來做的很少（功能閹割的不算數）。不過概念上都符合 OAuth 2 ，只是實作上有差。

我去看了以下這些網站的 OAuth 2 API 文件，清單是從 Wikipedia / OAuth / List of OAuth service providers 找來的。為了排版美觀， Grant Type 的 Authorization Code 簡寫成 Auth Code， Client Credentials 簡寫成 Client Cred.，Resource Owner Password 簡寫成 Password。檢閱日期是 2013 年 9 月 27 日，未來各 API 可能會改變，導致下表的情況跟現況不一致。

大概總結一下：

關於 Endpoints:

• GitHub 和 Basecamp 省略了 response_type 和 grant_type ，猜測是因為只有一種流程。但一樣情況的 Twitter 、 BOX 、新浪微博，則依然要傳 switch 參數。
• 通常 Authorization Endpoint 都是跟主站放在一起的，而不是放在 API 裡面，我想這個目的是要讓 User 直接用 cookie 登入並授權。

關於 Grant Types:

• 幾乎大家都至少會支援 Authorization Code Grant （Twitter 不支援）。
• 適合實作第三方登入的尤其會支援 Implicit 來做無縫接入（新浪微博似乎是個例外）。
• Client Credentials 很少有人會支援（Twitter 用來給 App 存取「非代表使用者」的資料）。
• Resource Owner Password 很少有人支援。GitHub 有一種類似的用法，但不是照規格，而是一種自製的流程。
• 除了內建的四種 Grant Types ，某些服務還會設計自己的 Grant Type，像是 Microsoft 就有一個叫 Sing-In Control Flow ，是 Implicit 的一種變體。

關於 Client Authorization （認證）：

• 大部份都有支援 POST
• 並非全部都有支援 HTTP Basic Auth ，但規格書裡面規定的是要至少支援 Basic Auth ，因為這一點，所以我把很多個服務標成「不相容 spec」
• 少數有使用 GET

關於資料格式：

• space 的分隔符 (delimiter) 很多用 , 逗號 (comma) ，照規格書用空格 (space) 的也有，不過還有完全不存在 "scope" 的概念，授權範圍就是完全存取。
• Microsoft 的 delimiter 我不知道到底是用什麼，詳情見下文。
• Token Type 雖然不是每個都是 "Bearer" ，但基本上概念都接近。目前沒有看到使用 MAC Token 的。

其他：

• Refresh Token 不是大家都有支援。
• 某些服務會提供 SDK ，像是 Facebook 、新浪微博，這樣子在網頁、手機上面，不需要手動規劃流程，由 SDK 完成，這樣也可以防止 App 在流程中動手腳，偷走密碼之類的資料。

以下各服務的筆記。

Facebook

文件： https://developers.facebook.com/docs/facebook-login/login-flow-for-web-no-jssdk/

Grant Types

• Authorization Code
• Implicit
• Client Credentials (用來取得 App Access Token)

Endpoints

• Authorization Endpoint: https://www.facebook.com/dialog/oauth （非 graph.facebook.com）
• Token Endpoint: https://graph.facebook.com/oauth/access_token

特色

• 概念上跟 OAuth 2 雷同，但沒有完全照標準。
• scope 用逗號 , 分隔 （非標準）
• Client Authentication 用 GET （非標準）
• Authorzation Endpoint 有提供同時拿 Authorization Code 和 Access Token 的功能（我不清楚是什麼用途）
• Implicit Flow 在使用 Token 之前，建議 validate ，防偽造攻擊。詳見 Confirming Identity 段落。
• Token 分成很多種，分別有不同的用途。詳見 Access Tokens。
• Desktop App 的 Redirection URI 固定為 https://www.facebook.com/connect/login_success.html ，並要求開發者內嵌一個 browser （如 WebView），監視其 state change 來取得 Access Token。
• 有自己的 Token Refresh 機制，見 Re-authentication。
• Token Type 不是 Bearer Token，但用起來很像。

其他值得參考的文件：

• Access Tokens - 不同 Access Token 用於各種 Scenario 的詳細操作步驟
• Permissions - 即 scopes 的定義
• Login Security - 安全性指南
• Securing Graph API Calls - 建議跑在 Web Server 上面的程式，用數位簽章簽過 reqeust

關於固定的 Redirection URI

前面提到說它的 Redirection URI 固定為　https://www.facebook.com/connect/login_success.html ，這個 URI 我覺得很有意思，打開來是這樣的內容：（斷行是我自己加的，原文沒斷行）

Success <br /><b style="color:red">安全警告：請以保護密碼的相同態度處理以上網址，切勿和任何人分享。</b>
<script type="text/javascript">
setTimeout(function() {
  window.history.replaceState && window.history.replaceState({}, "", "blank.html#_=_");
},500);
</script>

看這段 JavaScript，用途是「500ms 之後自動把瀏覽器的歷史記錄消滅掉，並且讓現在網址變成 blank.html#_=_」。這是什麼用途呢？

我猜測搭配 Implicit Grant Flow 用的。在 Implicit Grant Flow 裡面， Access Token 會包在 Fragment 裡面（就是網址最後面的那個 #xxxx），這樣子一來會被 User-Agent 放進歷史記錄裡，二來如果人眼看得到這個 User-Agent 的 Location Bar ，就可以看到 Access Token 。

所以 Facebook 推薦給 Desktop App 的實作方式，就是程式監視內嵌的 User-Agent 的當前網址，看到這個固定的 Redirection URI ，就可以抓 Access Token 了。而不管有沒有抓到，網頁裡的 script 都會把 Access Toekn 消除掉。

又，這種 #_=_ 也常常在 Facebook 第三方登入的時候看到，我猜測也是基於相同的原因，不過還沒有證實。

GitHub

文件： http://developer.github.com/v3/oauth/

Grant Types

• Authorization Code
• Resource Owner Password （自製，非標準）

Endpoints

用於 Authorization Code:

• Authorization Endpoint: https://github.com/login/oauth/authorize
• Token Endpoint: https://github.com/login/oauth/access_token

Resource Owner Password Grant Flow 是自製的流程，叫做 Authorizations，用的是 RESTful API，不是直接套用 OAuth 標準。在 Grant 的時候不使用上述的 Endpoints。

特色

• scope 用 , 逗號區隔（非標準）
• Client Authentication 支援 POST Auth （非標準）
• 所謂「自製的 Resource Owner Password Grant Type」，我指的是 GitHub 另外提供「讓 Resource Owner 自行管理 Authorizations」的 API ，見 OAuth Authorizations API 段落。
• 因為 Endpoint 只需要支援 Authorization Code Grant ，所以省略了 respose_type 和 grant_type。
• 沒有 Refresh Token
• Token 沒有時效，亦即除非手動 revoke ，否則永遠有效。
• Token Type 不是 Bearer Token，但用起來很像。

GitHub.app 即是使用 OAuth

GitHub 的 Mac GUI 應用程式就是用 OAuth 來存取資料的。你可以打開 Keychain Access ，找到 "github.com/mac (you@example.com)" 這個項目，按 Show Password 就可以看到 OAuth Access Token 了：


用同樣的 Access Token 可以 call API：

$ curl -i -H "Authorization: token bXXXXXXXXXXXXXXXXXXXXXXXXXXXXXb" https://api.github.com/user
HTTP/1.1 200 OK
Server: GitHub.com
X-OAuth-Scopes: notifications, repo, user
X-Accepted-OAuth-Scopes: user, user:email, user:follow, site_admin
X-GitHub-Media-Type: github.beta
X-Content-Type-Options: nosniff
# 部份略

{
    "login": "chitsaou",
    "id": 10737
    (略)
}

Twitter

文件： https://dev.twitter.com/docs/auth/application-only-auth

Grant Types

• Client Credentials

Endpoints

• Token Endpoint: https://api.twitter.com/oauth2/token

特色

• 與 spec 相容
• 只准用在 Application-only Path ，即是「代表 App 操作」。如果要「代表 User 操作」，則必須走 OAuth 1.0a 的流程。見 OAuth Signed 文件。
• Client Authentication 用 Basic Auth （標準）。
• Access Token 使用 Bearer Token 標準 (RFC 6750) 。
• 沒有 Refresh Token
• Access Token 沒有時效，但文件裡提及 app credentials 會過期，這個我搞不懂。（原文是 Obtain or revoke a bearer token with incorrect or expired app credentials）
• 用 Bearer Token (RFC 6750)

Google

文件： https://developers.google.com/accounts/docs/OAuth2

Grant Types

• Authorization Code
• Implicit

還有一種 Grant Flow 叫做 "for Devices" ，這是專門為 User-Agent 功能很少的設備來設計的，例如遊戲機、印表機。

Endpoints

• Authorization Endpoint: https://accounts.google.com/o/oauth2/auth
• Token Endpoint: https://accounts.google.com/o/oauth2/token

特色

• scope 用空白分隔。（標準）。
• Client Authentication 用 POST （非標準）。
• 特別提到 Authorization Code Grant Flow 適用 Chrome App
• 特別提到 Implicit Grant Flow 最好 validate token （同 Facebook）
• 把 Native App 歸類在「使用 Authorization Code Grant Flow」裡面，但如此一來 secret 就不再是 secret ，會被抓出來。
• 對於 Native App，預設有一個 Redirection URI 叫做 urn:ietf:wg:oauth:2.0:oob 。跟 Facebook 的 Desktop App 指南一樣，這是可以給內嵌 browser 監視其 state change 來取得 Access Token 的方式。見 Using OAuth 2.0 for Installed Applications / Choosing a Redirect URI
• 有 Refresh Token
• 用 Bearer Token (RFC 6750)

Microsoft (Windows Live)

文件： http://msdn.microsoft.com/en-us/library/live/hh243647.aspx

Grant Types

• Authorization Code Grant
• Implicit
• Sign-in Control （自製，從 Implicit Flow 變化來的，本文略）

Endpoints

• Authorization Endpoint: https://login.live.com/oauth20_authorize.srf
• Token Endpoint: https://login.live.com/oauth20_token.srf

特色

• scope 分隔不明。（沒明說，照文件的範例是空格，但 omniauth-live-connect 卻是逗號）
• Client Authentication 用 POST （非標準）。
• 在 Authorization Code Grant Type Flow 裡面，可以自行指定 App 為 Desktop 或 Mobile ，這樣子 Redirection URI 會固定為 https://login.live.com/oauth20_desktop.srf 。跟 Facebook 的 Desktop App 指南一樣，要求開發者內嵌一個 browser （如 WebView），監視其 state change 來取得 Access Token。不過跟 Facebook 不同的是，它裡面打開是空空如也，沒有 script 來把 access token 藏起來。
• 有 Refresh Token
• Access Token 沒有時效，但文件裡提及 app credentials 會過期，這個我搞不懂。（原文是 Obtain or revoke a bearer token with incorrect or expired app credentials）
• Token Type 沒明說，但看起來也不是 MAC Token ，而是類似 Bearer Token。

Dropbox

文件： https://www.dropbox.com/developers/core/docs

Grant Types

• Authorization Code
• Implicit

Endpoints

• Authorization Endpoint: https://www.dropbox.com/1/oauth2/authorize （非 api.dropbox.com）
• Token Endpoint: https://api.dropbox.com/1/oauth2/token

特色

• 與 spec 相容
• 沒有 scope 的概念
• Client Authentication 支援 Basic Auth 和 POST Auth
• 用 Bearer Token (RFC 6750)

Amazon

文件： http://login.amazon.com/website 裡面的一份 PDF

Grant Types

• Authorization Code
• Implicit

Endpoints

• Authorization Endpoint: https://www.amazon.com/ap/oa （非 api.amazon.com）
• Token Endpoint: https://api.amazon.com/auth/o2/token

特色

• 與 spec 相容
• scope 用空格分隔（標準）。
• Client Authentication 支援 Basic Auth 或 POST （標準）。
• 特別提到 Implicit Grant Flow 最好 validate token （同 Facebook）
• 有 Refresh Token
• 使用 Bearer Token (RFC 6750)。

另外文件裡面還提到安全性問題 (Security Considerations)，是從 Spec 的 Security Considerations 來的，但比 spec 的好讀……。

其中我特別注意到的幾點：

• CSRF - 建議把 state 用 HMAC 編碼過，其 secret 就是 client secret 。
• Implicit Flow 的 Resource Owner 偽裝 - 建議要向 Server 驗證 Access Token。
• Open Redirector - 最好不要在 Redirection Endpoint 裡面放 &url=xxx 這種東西。
• Code Injection - 最好把 state 驗證過沒問題再拿來用，顧客資料 (customer profile) 也要如此做。

Bit.ly

文件： http://dev.bitly.com/authentication.html

Grant Types

• Authorization Code (部份自製，非標準)
• Resource Owner Password

Endpoints

• Authorization Endpoint: https://bitly.com/oauth/authorize
• Token Endpoint: https://api-ssl.bitly.com/oauth/access_token

特色

Bit.ly 的情況比較特別，它雖然有 Authorization Code Grant Flow ，但實作的細節卻跟 OAuth 2.0 有點不同，這個不同就導致它與 spec 不相容：

• 發 Access Token 不用 JSON 而是用 URL-encoded string （但 Password Grant 卻是用 JSON）。
• Client Authentication 用 POST 而不是 Basic Auth （但 Password Grant 卻是用 Basic Auth 而不是 POST）。

其他特色：

• 沒有 scope 的概念。
• Client Authentication 用 Basic Auth （Password Grant）或 POST （Auth Code Grant），互相不能交換。
• 沒有 Refresh Token
• Token Type 沒有明說是哪一種。

新浪微博

文件： http://open.weibo.com/wiki/%E6%8E%88%E6%9D%83%E6%9C%BA%E5%88%B6%E8%AF%B4%E6%98%8E

Grant Types

• Authorization Code
• Implicit

Endpoints

• Authorization Endpoint: https://api.weibo.com/oauth2/authorize
• Token Endpoint: https://api.weibo.com/oauth2/access_token

特色

• scope 用逗號 , 分隔（非標準）。
• Client Authentication 用 Basic Auth（標準）和 GET。
• 有 Refresh Token
• 有 Token 自動展期機制。
• Token Type 不是 Bearer Token。 Call API 的時候可以用 GET 或 Header 送 token。
• 有對 Client 分等級，不同等級有不同的 Rate Limiting 和 Token 時效。

另外它還提供了应用安全开发注意事项這份文件可以參考，雖然是從 Spec 裡面的 Security Considerations 拉出來的。

豆瓣

文件： http://developers.douban.com/wiki/?title=oauth2

Grant Types

• Authorization Code
• Implicit

Endpoints

• Authorization Endpoint: https://www.douban.com/service/auth2/auth
• Token Endpoint: https://www.douban.com/service/auth2/token

特色

• scope 用逗號 , 分隔（非標準）。
• Client Authentication 用 POST （非標準）。
• 有 Refresh Token
• 用 Bearer Token (RFC 6750)。
• 有對 Client 分等級，不同等級有不同的 Rate Limiting 和 Token 時效。
• Error Response 是自己設計的標準，有自己定義錯誤代碼表，其中不少是直接從 OAuth 2.0 Spec 來的。

BOX

文件： http://developers.box.com/oauth/

Grant Types

• Authorization Code

Endpoints

• Authorization Endpoint: https://www.box.com/api/oauth2/authorize
• Token Endpoint: https://www.box.com/api/oauth2/token

特色

• 沒有 scope 的概念。
• Client Authentication 用 POST （非標準）。
• 有 Refresh Token
• 使用 Bearer Token (RFC 6750)。
• 對於「禁止轉回 Redirection Endpoint」的錯誤情況，會出現一個精美的頁面來提示錯誤。
• 有 self-revoke 的流程。

Basecamp (37signals)

文件： https://github.com/37signals/api/blob/master/sections/authentication.md

Grant Types

• Authorization Code

Endpoints

• Authorization Endpoint: https://launchpad.37signals.com/authorization/new
• Token Endpoint: https://launchpad.37signals.com/authorization

特色

• 沒有 scope 的概念。
• Client Authentication 用 POST （非標準）。
• 有 Refresh Token
• 用 Bearer Token (RFC 6750)。
• 改密碼就會直接 revoke Access Tokens 。

OAuth 2.0 系列文目錄

• (1) 世界觀
• (2) Client 的註冊與認證
• (3) Endpoints 的規格
• (4.1) Authorization Code Grant Flow 細節
• (4.2) Implicit Grant Flow 細節
• (4.3) Resource Owner Credentials Grant Flow 細節
• (4.4) Client Credentials Grant Flow 細節
• (5) 核發與換發 Access Token
• (6) Bearer Token 的使用方法
• (7) 安全性問題
• 各大網站 OAuth 2.0 實作差異 ← You Are Here

以下的次標題都是我自己加的。

除了 Spec 裡面提到的這些，我還有找到一些 service provider 有提供安全性指南，可以參考：

• Login Security - Facebook Developers
• 应用安全开发注意事项 - 新浪微博API
• Amazon OAuth 文件的 Security Considerations

Client 認證的安全性問題 (Section 10.1)

見系列文第 2 篇。

偽裝成別的 Client (Section 10.2)

見系列文第 2 篇。

Access Token 的安全性問題 (Section 10.3)

保密傳輸、保密儲存

Access Token 的 crednetials 以及任何機密的 Access Token 屬性，都必須要保密傳輸、保密儲存，並且只能在以下角色之間流通：

• Authrization Server
• Access Token 搭配的 Resource Server
• Access Token 所核發的對象 Client

Access Token credentials 必須只能經過 TLS 傳輸，還要搭配 Server Authentication （定義在 RFC 2818: HTTP over TLS）。

Implicit Flow 的 Token 外洩風險

Implicit Grant Type Flow 的 Access Token 是經過 URI Fragment 傳輸的，可能會外洩給未經授權的第三方。

防猜猜樂攻擊

Authorization Server 必須確保 Access Token 不會被未經授權的第三方自動產生、被修改、被猜出如何產生可以用的。

決定 scope 時可以對 Client 階級歧視

Client 請求 Access Token 的時候，應該只請求最少需要的 scope 。Authorization Server 在選擇如何遵守所請求的 scope 的時候，應該要考慮 Client 的身份，並且可以核發少於所求的 scope 的 Access Token。（編按：亦即決定 scope 的時候，可以對 Client 實施階級歧視）

無機制來確保 Access Token 的權威性

Spec 不為 Resource Server 提供任何方法來確保 Client 出示的 Access Token 真的是 Authorization Server 核發的。

Refresh Token 的安全性問題 (Section 10.4)

核發對象

Authorization Server 可以核發 Refresh Token 給這些 Clients：

• Web Application Clients （跑在 Server 上）
• Native Application Clients

（編按： Angular.js 之類的 client-side app 算 UA-based Clients ，不可以核發 Refresh Token）

保密傳輸、保密儲存

Refresh Token 必須要保密傳輸、保密儲存，並且只能在以下角色之間流通：

• Authrization Server
• Refresh Token 核發的對象 Client

Authorization Server 必須把 Refersh Token 和被核發的 Client 綁定。

Refresh Token credentials 必須只能經過 TLS 傳輸，還要搭配 Server Authentication （定義在 RFC 2818: HTTP over TLS）。

（編按：除了「不能給 Resource Server」 、「要求必須綁定 Client」 ，其他跟 Access Token 的保密要求一樣）

自動把舊的 Token 撤銷掉

例如，Authorization Server 可以實施 Refresh Token Rotation ：

• 每一次換發 Access Token 的時候，一併換 Rrefresh Token
• 之前的 Referesh Token 就變成無效
• 但是保留在 Authorization Server 裡面

如果 Refresh Token 被偷，還隨後被壞人和合法的 Client 同時使用，那麼其中一個將會出示無效的 Refresh Token ，這樣 Authorization Server 就可以甄別兩方，壞人就會破功。

防猜猜樂攻擊

Authorization Server 必須確保 Refresh Token 不會被未經授權的第三方自動產生、被修改、被猜出如何產生可以用的。

Authorization Code 的安全性問題 (Section 10.5)

見系列文第 4.1 篇。

竄改 Authorization Code 的 Redirection URI (Section 10.6)

見系列文第 4.1 篇。

Resource Owner Password Credentials 的安全性問題 (Section 10.7)

見系列文第 4.3 篇。

Request 的加密傳輸 (Section 10.8)

以下這些資訊禁止沒加密就傳輸：

• Access Token
• Refresh Token
• Resource Owner Passwords
• Client Credentials

Authorization Code 最好不要沒加密就傳輸。（不強求）

state 和 scope 參數最好不要明文內嵌關於 Client 或 Resource Onwer 的敏感資訊，因為他們可能會沒有加密傳輸、加密儲存。

（編按：這裡的加密傳輸我解釋為 TLS）

確保 Endpoint 的權威性 (Authenticity) (Section 10.9)

為了防止中間人攻擊，對於往 Authorization Endpoint 和 Token Endpoint 的 requests：

• Authorization Server 必須要有 TLS 加上伺服器認證 (RFC 2818)
• Client 必須驗證 Server 的 TLS 憑證 (RFC 6150)，and in accordance with its requirements for server identity authentication （看不懂，保留原文…）。

（編按：我理解為必須檢驗憑證的合法，以及憑證鏈的合法。如果 SSL 憑證過期、網域名稱不對、或被 revoke ，或憑證鏈不合法，則視為不合法。）

Credential 猜猜樂攻擊 (Section 10.10)

Authorization Server 必須防止壞人可以猜到：

• Access Token （自動產生）
• Authorization Code （自動產生）
• Refresh Token （自動產生）
• Resource Owner Password （使用者自己持有）
• Client Credential （自動產生）

至於猜中機率的要求：

對於自動產生、非使用者自己持有的資料，猜中的機率必須不高於 1/(2^128) （2 的 128 次方分之 1）、並且應該不高於 1/(2^160) （2 的 160 次方分之 1）。（編按：所謂 2 的 n 次方分之 1 ，指的是資料的可能性有 2 的 n 次方這麼多種，實務上就是長度為 n-bit 的資料。）

對於使用者自己持有的資料， Authorization Server 必須使用其他手段來保護之。

釣魚攻擊 (Section 10.11)

大範圍部署 OAuth 等類似的通訊協定，可能會導致使用者習慣於被轉向到別的網站，在那邊被要求填入密碼。如果使用者在輸入密碼之前，不謹慎確認這些網站的權威性 (authenticity) ，就可能讓壞人利用這個習慣來偷取 Resource Owner 的密碼。

OAuth 的服務提供者應該要嘗試教育使用者關於釣魚攻擊的風險，並且應該要提供一種機制來讓使用者可以很容易就確認正牌網站的權威性。Client 開發者也應該要考慮到安全衝擊，像是使用者會怎麼與 User-Agent 互動（內嵌或外部瀏覽器），以及使用者是否有能力核實 Authorization Server 的權威性。

為了降低釣魚攻擊的風險， Authorization Server 必須在每個用來與使用者互動的 Endpoints 都要求 TLS 。

CSRF (Section 10.12)

CSRF (Cross-site request forgery) 是一種攻擊手段，壞人讓受害使用者的 User-Agent 跟隨惡意的 URI （例如會以誤導的連結、圖片、轉址等形式提供給 User-Agent）跑到信任的伺服器（通常是透過一個合法的 session cookie 來達成）。

對 Client 的 CSRF 攻擊

對 Client 的 Redirection URI 的 CSRF 攻擊，可以讓壞人注入他自己的 Authorization Code 或 Access Token ，這樣會導致 Client 直接使用一個連結到壞人的 Protected Resource 的 Access Token ，而不是受害者自己的 Access Token （例如，把受害者的銀行帳戶資訊儲存到壞人所控制的 Protected Resource）。

Client 必須在 Redirection URI 實作 CSRF 防範。通常的做法是：

• 要求任何 request 附帶一個值，這個值綁定到 User-Agent 的一個獲授權的狀態（例如把一個用來認證 User-Agent 的 session cookie 給 hash 過之後的數值）
• 當 Client 發出 Authorization request 到 Authorization Server 的時候，Client 應該要使用 state 參數來傳遞這個值。
• 在使用者授權之後，Authorization Server 會把使用者的 User-Agent 轉向回 Client 並附上 state 參數。
• Client 可以檢查這個綁定值是否跟 User-Agent 獲授權的狀態相同，來確認 request 的合法與否。

其用來防範 CSRF 的綁定值，必須包含一個無法猜測的值（如 Section 10.10 所述），且 User-Agent 的獲授權的狀態（session cookie 、 HTML5 local storage 等）必須保存在一個只有 Client 的 User-Agent 可以存取的地方（也就是說要用 same-origin policy 保護）。

在 Amazon 的文件 裡面，是建議把 state 用 HMAC 簽過，secret 就用 Client Secret ，這樣可以防止人家偽造。

對 Authorization Server 的 CSRF 攻擊

對 Authorization Endpoint 的 CSRF 攻擊，可以讓壞人在使用者未參與或未獲警告的情況下，取得給惡意 Client 的使用者授權。

Authorization Server 必須在 Authorization Endpoint 實作 CSRF 防範，並且確保惡意的 Client 不會在 Resource Owner 不知情、沒有明確許可的情況下取得授權，

Clickjacking （點擊綁架） (Section 10.13)

在 Clickjacking 攻擊裡面，壞人會這樣做：

• 註冊一個合法的 Client。
• 造一個惡意網站，在這網站裡面，有一個透明的 iframe 會載入 Authorization Server 的 Authorization Endpoint 網頁。
• iframe 覆蓋在一組假造的按鈕之上，這精心製作的按鈕會直接放在授權頁面的重要按鈕的下面。
• 當使用者看到那誤導按鈕，並且按下去，使用者實際上是按下了疊在授權頁面之上的隱藏按鈕（例如「給予授權」按鈕）。

如此攻擊者可以晃點 Resource Owner ，讓他不經意授權了 Client 的存取權，而使用者卻不知情。

為了防範這種型式的攻擊， Native Application 在請求使用者授權的時候，最好要使用外部 browser ，而非內嵌一個 browser 到應用程式裡面。對於多數的新瀏覽器來說，可以使用 "X-Frame-Options" header （非標準） 來強制要求 Authorization Server 的網頁不能從 iframe 載入。這個 header 可以有兩種值，分別是 "deny" （禁止其從任何框架頁載入）和 "sameorigin" （只允許同樣 origin 的網站透過框架頁載入）。對於舊的瀏覽器來說，JavaScript Frame-Busting 技術可能可以用，但不見得對所有瀏覽器都有效。

相關資料：

• The X-Frame-Options response header - HTTP | MDN
• Combating ClickJacking With X-Frame-Options - IEInternals - Site Home - MSDN Blogs

程式碼注入以及輸入值的驗證 (Section 10.14)

當輸入值或是其他外部參數沒有被消毒 (sanitizied) 導致改變了應用程式的內部邏輯的時候，就是發生了程式碼注入攻擊。這可能會允許壞人取得應用程式裝置或資料的存取權、造成服務阻斷 (DoS) 、或是造成更大範圍的不良副作用。

Authorization Server 必須對任何接收到的資料消毒（可以的話還要驗證是否正確），特別是 "state" 和 "redirection_uri" 參數。

Open Redirectors (Section 10.15)

見系列文第 3 篇。

誤用 Access Token 來在 Implicit Flow 裡面偽裝 Resource Owner (Section 10.16)

見系列文第 4.2 篇。

OAuth 2.0 系列文目錄

• (1) 世界觀
• (2) Client 的註冊與認證
• (3) Endpoints 的規格
• (4.1) Authorization Code Grant Flow 細節
• (4.2) Implicit Grant Flow 細節
• (4.3) Resource Owner Credentials Grant Flow 細節
• (4.4) Client Credentials Grant Flow 細節
• (5) 核發與換發 Access Token
• (6) Bearer Token 的使用方法
• (7) 安全性問題 ← You Are Here
• 各大網站 OAuth 2.0 實作差異

實際上，即使有定義這個 Bearer Token ，各大網站的 API 也並非都使用這種 Token ，我看到有明確說明使用 Bearer Token 的像是 Twitter API，其他的要不是非使用 "Bearer" 關鍵字，就是沒有明確指出何種 Token （其實也不需要，因為在那些網站 Token 只有一種用途）。

不過即使如此，對於我打算實作的 API ，我也是準備使用 Bearer Token 的，因為夠 naïve 。如果你跟我一樣沒有自己刻 Token 的能力，就用 Bearer Token 就好了。

當然， RFC 6750 我也有轉成 Markdown 好讀版。

Bearer Token 的用途

OAuth 2.0 (RFC 6749) 定義了 Client 如何取得 Access Token 的方法。Client 可以用 Access Token 以 Resource Owner 的名義來向 Resource Server 取得 Protected Resource ，例如我 (Resource Owner) 授權一個手機 App (Client) 以我 (Resource Owner) 的名義去 Facebook (Resource Server) 取得我的朋友名單 (Protected Resource)。OAuth 2.0 定義 Access Token 是 Resource Server 用來認證的唯一方式，有了這個， Resource Server 就不需要再提供其他認證方式，例如帳號密碼。

然而在 RFC 6749 裡面只定義抽象的概念，細節如 Access Token 格式、怎麼傳到 Resource Server ，以及 Access Token 無效時， Resource Server 怎麼處理，都沒有定義。所以在 RFC 6750 另外定義了 Bearer Token 的用法。Bearer Token 是一種 Access Token ，由 Authorization Server 在 Resource Owner 的允許下核發給 Client ，Resource Server 只要認這個 Token 就可以認定 Client 已經經由 Resource Owner 的許可，不需要用密碼學的方式來驗證這個 Token 的真偽。關於 Token 被偷走的安全性問題，此 Spec 裡面也有提到。

本段參考 Abstract 及 Section 1

Bearer Token 的格式

Bearer XXXXXXXX

其中 XXXXXXXX 的格式為 b64token ，ABNF 的定義：

b64token = 1*( ALPHA / DIGIT / "-" / "." / "_" / "~" / "+" / "/" ) *"="

寫成 Regular Expression 即是：

/[A-Za-z0-9\-\._~\+\/]+=*/

本段參考 Section 2.1

Client 向 Resource Server 出示 Access Token 的方式

三種

(1) 放在 HTTP Header 裡面

GET /resource HTTP/1.1
Host: server.example.com
Authorization: Bearer mF_9.B5f-4.1JqM

Resource Server 必須支援這個方式。

本段參考 Section 2.2

(2) 放在 Request Body 裡面（Form 之類的）

POST /resource HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded

access_token=mF_9.B5f-4.1JqM

前提：

• Header 要有 Content-Type: application/x-www-form-urlencoded。
• Body 格式要符合 W3C HTML 4.01 定義 application/x-www-form-urlencoded。
• Body 要只有一個 part （不可以是 multipart）。
• Body 要編碼成只有 ASCII chars 的內容。
• Request method 必須是一種有使用 request-body 的，也就是說不能用 GET 。

就是送表單嘛，但不可以是 multipart/form-data 這種（通常用來上傳檔案）。

Resource Server 可以但不一定要支援這個方式。

本段參考 Section 2.3

(3) 放在 URI 裡面的一個 Query Parameter （不建議）

規定要使用 access_token 這個 parameter ，例：

GET /resource?access_token=mF_9.B5f-4.1JqM HTTP/1.1
Host: server.example.com

然而因為 URL 可以被 proxy 抄走（如 log）或存在瀏覽器的歷史記錄裡面，為了防 replay ，最好這樣做：

• Client 送 Cache-Control: no-store header
• Server 回 2xx 的時候，送 Cache-Control: private header

Spec 不建議使用這種方法，如果真的沒辦法送 header 也沒辦法透過 request-body 送，再來考慮這種。

Resource Server 可以但不一定要支援這個方式。

本段參考 Section 2.4

Resource Server 向 Client 提示「認證不過，拒絕存取」的方式

拒絕存取的情況，例如沒給 Access Token 或是給了但不合法（如空號、過期、Resource Owner 沒許可 Client 拿取此資料），則 Resource Server 必須在回應裡包含 WWW-Authenticate 的 header 來提示錯誤。這個 header 定義在 RFC 2617 Section 3.2.1。WWW-Authenticate 的值，使用的 auth-scheme 是 Bearer ，隨後一個空格，接著要有至少一個 auth-param 。

範例：

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="example",
                  error="invalid_token",
                  error_description="The access token expired"

以下這些 auth-params 是 WWW-Authenticate 會用到的：

realm

用 realm 來指出需要授權才能存取的範圍，意義跟 HTTP Authentication 的 realm 一樣。realm 只能出現一次。

scope

用 scope 來指出「要拿這個 Resource 需要出示具有哪些 scope 的 Access Token 」：

• 要區分大小寫。
• 要以空白分隔。
• 可以用哪些 scope ，是看 Authorization Server 怎麼定義，Spec 不定義，也沒有登錄中心。
• 順序不重要。
• 是給程式看的，不是設計給使用者看的。

scope 還可以在向 Authorization Server 索取新 Access Token 的時候使用。

scope 值只能出現一次。實際寫在 scope 裡面的單一個 scope 必須只能用以下的字元，定義在 RFC 6749 附錄 A.4 ：

\x21, \x23-\x5b, \x5d-\x7e

即可見的 US-ASCII 字元裡面，除了雙引號 " (\x22) 和反斜線 \ (\x5c) 以外。空格當然也不能用，因為是用來區分不同 scopes 的。

error

如果 Client 出示了 Access Token 但認證失敗，則最好加上 error 這個 auth-param ，用來告訴 Client 為何認證失敗。此外還可以加上 error_description 用自然語言來告訴開發者為什麼錯誤，但這個不該給使用者看到。此外也可以加上 error_uri 用來提供一個網址，裡面用自然語言解釋錯誤訊息。這三個 auth-param 都只能最多出現一次。

如果 request 沒有出示 Access Token （例如 Client 不知道需要認證，或是使用了不支援的認證方式（例如不支援 URI parameter）），則 response 不應該帶 error 或任何錯誤訊息。

error 的值的意義以及推薦使用的 HTTP response code 如下：

error 和 error_description 的值必須只能用以下的字元，定義在 RFC 6749 附錄 A.7 和 RFC 6749 附錄 A.8：

\x20-\x21, \x23-\x5b, \x5d-\x7e

即空格 (\x20) 再加上可見的 US-ASCII 字元裡面，除了雙引號 " (\x22) 和反斜線 \ (\x5c) 以外。

error_uri 的值必須符合 RFC 3986 的定義，即是只能用以下的字元（同 scope 裡面的單一 scope）：

\x21, \x23-\x5b, \x5d-\x7e

即可見的 US-ASCII 字元裡面，除了雙引號 " (\x22) 和反斜線 \ (\x5c) 以外。

本段參考 Section 3 及 Section 3.1

Authorization Server 給 Client 核發 Access Token 的範例

既然是 OAuth 2.0 的 access token ，就通常是循 OAuth 2.0 的 spec 來核發，範例如下：

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "access_token":"mF_9.B5f-4.1JqM",
  "token_type":"Bearer",
  "expires_in":3600,
  "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA"
}

本段參考 Section 4

安全性問題與對策

RFC 6750 是基於 OAuth 2.0 RFC 6749 來寫的，所以在該 spec 裡面提過的安全性問題就不再提及。

原文將問題與問題對策分開成 Section 5.1 和 Section 5.2 ，我為了方便筆記，所以合併在一起。以下「壞人」的原文是 attacker。

一般對策

大部份的安全性問題可以透過數位簽章或是 MAC (Message Authentication Code) 來防護。

Authorization Server 必須有實作 TLS，版本則隨時間推移而不同。 spec 作成的時候， TLS 最新版是 1.2 ，但實務上很少使用，1.0 才是最為廣泛利用的。

偽造或竄改 Access Token 的問題

壞人可能會偽造或竄改既有的 Access Token （竄改指的是修改授權範圍或授權參數），讓 Resource Server 給予 Client 不適當的存取權。例如，壞人可能會延長 Token 的過期時間。或是惡意的 Client 變造聲明來看到它不應該看到的東西，例如，告訴使用者只拿取公開的個人資料，卻在取得授權時，另外拿了朋友名單。

Section 5.1 > Token manufacture/modification

對策

對於 Bearer Token ，可以只加一個參照用的 id 來間接指到真正的授權資訊，而不是直接燒在 Token 裡面。這種間接參照用的 id ，必須要難以被猜到；但使用間接參照，因為要間接檢查授權資訊，所以可能會導致 Resource Server 和 Authorization Server 之間有額外的動作※。這種機制的細節，spec 裡面沒有定義。

Spec 沒有定義 token 的編碼方式，所以不提及保護 Token 的完整性 (integrity) 的詳細建議。若要實作保護完整性的措施，則該實作方式必須要可以防止 Token 被竄改。

※：原文是 "between a server and the token issuer"

Access Token 傳輸過程外洩、曝露敏感資料的問題

Token 傳輸過程可能被監聽而外洩，或 Token 本身可能會包含敏感資料※。

※在 Section 5.1 原文提及 "token disclosure" 的時候，僅提及曝露敏感資料，沒提及傳輸過程的外洩，然而 5.2 裡面關於 "token disclosure" 的對策，有一併提及傳輸過程外洩（中間人攻擊、監聽等），所以我寫這一段時，同時提及傳輸外洩以及曝露敏感資料。

Section 5.1 > Token disclosure

對策

為了防範 Token 在傳輸過程外洩，必須用 TLS 來實作機密防護，且該實作方式必須要使用有提供機密防護和完整性防護的加密方式，如此就能要求 Client 與 Authorization Server 和 Client 與 Resource Server 之間的通訊要有機密防護和完整性防護。因為 TLS 是這份 spec 裡面規定一定要實作的，所以利用 TLS 來達成通訊過程的機密防護和完整性防護，是比較偏好的做法。

如果要防止 Client 取得 Token 的內容，那麼除了 TLS 之外，還必須實作 Token 加密。

要進一步防範 Token 外洩，則 Client 在發 request 的時候，還必須要驗證 TLS 的憑證鏈 (certificate chain) ，包括檢查憑證有沒有被撤銷（Certificate Revocation List, RFC 5280）。

Cookie 通常是明文傳輸的 (in the clear)，所以任何寫在裡面的資訊都有外洩的風險。所以， Bearer Token 絕對不可以存放在明文傳輸 cookie 裡面。詳見 RFC 6265 (HTTP State Management Mechanism) 裡面關於 cookie 的安全性問題。

某些部署方式，好比說利用 Load Balancer 的，TLS 傳輸在抵達 Resource Server 之前就結束了。這樣子會導致 Token 在前端 Load Balaner 和後端實體 Resrouce Server 之間，沒有加密保護。這種情況下，必須實作足夠的手段※，來確保前端和後端 server 之間的資料保密。Token 加密也是一種方式。

※ 原文為 sufficient measures，我不會翻譯…

挪用 Access Token 的問題

壞人可能會把某個專門給 Resource Server A 的 Access Token ，挪用到 Resource Server B ，使得 B 誤信該 Access Token 可以拿來存取 B 的資料。

Section 5.1 > Token redirect

對策

要防止 Token 被挪用，則這件事很重要：Authorization Server 核發的 Token 裡面要附上被核發人的資訊（通常是一或多部 Resource Server）。同時，也建議限制 Token 可以使用的 scope 範圍。

二度利用 Access Token 的問題

壞人使用之前就存在的 Access Token 來存取 Reseouce Server （即：Token 被偷去用）。

Section 5.1 > Token replay

對策

要防止 Token 被偷走並且拿來二度利用，建議採用以下方案：

1. Token 的存活時間必須被限制住。一種手段是在 Token 受保護的區段裡面，設一個合法期間。使用短時效的 Token （如一小時以下）可以降低 Token 外洩的風險。

• Token 在 Client ↔ Authorization Server 、 Client ↔ Resource Server 之間交換的時候，必須要實作機密防護。如此一來，就算在傳輸途徑上監聽，也無法獲得 Token ，也就無法二度利用。
• Client 要向 Resource Server 出示 Token 的時候，Client 必須驗證 Resource Server 的真實身份，如 RFC 2818 (TLS) 的 Section 3.1 裡面所述。注意，Client 必須要驗證 TLS 憑證的憑證鏈 (certificate chain)。若 Resource Server 未經授權且未通過認證，或是憑證鏈驗證失敗，這時候向它出示 Token ，會導致敵手取得 Token 並且得到未經授權的權限來存取受保護的 resource。

安全性建議的總結

Section 5.3 Summary of Recommendations

要藏好 Bearer Token

Client 實作必須確保 Bearer Token 不會外洩給無關人士，因為他們可以以此來存取受保護的 resources。利用 Bearer Token 時，這是首要的安全性考量，且優先於其他更細節的建議。

要驗證 TLS 的憑證鏈

當 Client 發 request 索取受保護的 resources 的時候，Client 必須驗證 TLS 的憑證鏈。若做不到的話，可能會引發 DNS 劫持，導致 Token 被壞人偷走。

全程使用 TLS (https)

當 Clients 利用 Bearer Token 發 request 時，Client 必須一直使用 TLS (RFC5246) (https) 或同等的安全傳輸。若做不到的話， Token 會曝露在各種攻擊方式，讓壞人可以得到意料之外的存取權。

不要把 Bearer Token 存在 Cookie

絕對不可以把 Bearer Token 存在可以明文傳輸 (sent in the clear) 的 Cookie 裡面（明文傳輸是 cookie 傳輸的預設方式）。若存在 Cookie 裡面，必須要小心 Cross-Site Request Forgery 。

要核發短時效的 Bearer Token

核發 Token 的伺服器最好是核發短時效的 Bearer Token （一小時以內），尤其是發給跑在瀏覽器裡面的 Client ，或是其他容易發生資訊外洩的場合。利用短時效的 Bearer Token 可以降低 Token 外洩時的衝擊。

要核發有區分使用範圍的 Bearer Token

Token 伺服器最好要核發包含 audience restriction, scoping their use to the intended replying party, or set of relying party 的 Token 。

不要用 Page URL 來傳送 Bearer Token

Bearer Token 最好不要從 URL 來傳送（例如 query parameter），而最好是從有保密措施的 HTTP header 或是 body 來傳輸※。瀏覽器、伺服器等軟體可能不會把歷史記錄或資料結構給妥善加密。如果 Bearer Token 透過 URL 傳輸，則壞人就有可能可以從歷史記錄取得之。

※ "be passed in HTTP message headers or message bodies for which confidentiality measures are taken"

OAuth 2.0 系列文目錄

• (1) 世界觀
• (2) Client 的註冊與認證
• (3) Endpoints 的規格
• (4.1) Authorization Code Grant Flow 細節
• (4.2) Implicit Grant Flow 細節
• (4.3) Resource Owner Credentials Grant Flow 細節
• (4.4) Client Credentials Grant Flow 細節
• (5) 核發與換發 Access Token
• (6) Bearer Token 的使用方法 ← You Are Here
• (7) 安全性問題
• 各大網站 OAuth 2.0 實作差異

Response 的規格

Status Code: 200 OK

Header 裡面一定要有這些：

• Pragma: no-cache
• Cache-Control: no-store （如果有 Token 、有 Credential 或是其他敏感資料）

回應的是 JSON，所以：

• 參數要編碼成 JSON 格式
• 編碼完成的 JSON 放在 Response Body 裡面
• 字串 (String) 要符合 JSON String 格式（好比說有些字元要 escape）
• 數字 (Number) 要符合 JSON Number 格式

每一個參數都放在 JSON 的第一層。

核發 Access Token

如果 Access Token Request 合法且經授權，則 Authorization Server 會核發 Access Token 以及 Refresh Token （不一定有，看 Access Token 支援以及流程允許與否，例如 Implicit Grant Type 就禁止核發 Refresh Token）。

如果 Access Token Request 失敗，像是 Client 認證不過，或是 Request 不正確，那麼 Authorization Server 會回傳 Error ，本文最末提及。

以下是核發 Access Token 驗證程序都正確、要核發的時候的規格。

參數

Client 收到不認識的參數必須忽略之。參數的長度（含 token）在 spec 裡面都不定義，Client 不可以自行瞎猜，Authorization Server 的文件裡面應該要提到。

其中 scope 如果和申請的不同則要附上，如果一樣的話就不必附上。

其中 refresh_token ，可以用來申請新的 Access Token。不一定會有，甚至 Client Credentials Grant Type 就建議不要發。

範例

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "access_token":"2YotnFZFEjr1zCsicMWpAA",
  "token_type":"example",
  "expires_in":3600,
  "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
  "example_parameter":"example_value"
}

換發 Access Token

換發 (Refreshing) Access Token ，指的是目前的 Access Token 過期、權限不足，而需要取得新的 Token 。可以換發的前提，的前提，是 Authorization Server 之前有核發 Refresh Token 。如果沒有，就不行。Client 可以自動做這件事（像是已知 Token 過期）。

Refresh Token 通常是會存在很久的 token ，且是用來拿取新的 Access Token 的，所以要綁定到被核發的 Client。

換發新的 Access Token 的時候，可以一併核發新的 Refresh Token ，這樣子的話 Client 必須把舊的 Refresh Token 丟掉，換成新的。同時， Authorization Server 也可以撤銷舊的 Refresh Token 。需注意新的 Refresh Token 其 scope 也要跟舊的 Refresh Token 一致。

換發 Access Token 的 Request 是發到 Token Endpoint ，用 POST。

參數

其中 scope 絕對不可以包含之前 Resource Owner 沒有授權過的。如果沒給這個參數，則直接沿用之前授權過的那些。

Authorization Server 的處理程序

這個 Request 進來的時候， Authorization Server 要做這些事：

1. 要求 Client 認證自己（如果是 Confidential Client 或有拿到 Client Credentials）

• 如果 Client 有出示認證資料，就認證它，細節見系列文第 2 篇
• 確定 Refresh Token 是發給 Client 的
• 驗證 Refresh Token 正確

如果都沒正確，就照核發 Access Token 的方式回 Response （本文「核發 Access Token」一段）。

範例

Client 向 Token Endpoint 換發新的 Access Token

POST /token HTTP/1.1
Host: server.example.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA

發生錯誤時的回應方式

Status Code: 400 Bad Request （若無特別規定就用這個）

Header 和 Format (JSON) 跟核發的時候一樣。

參數

基本上跟 Authorization Code Grant Flow 裡面的 Authorization Endopint 的錯誤參數一樣，差別在於 error 的錯誤代碼可以用的不一樣。

而 error 的值是以下的其中一個：

其中 invalid_client ：

• Status code 可以用 401 Unauthorized
• 如果 Client 是用 Authorization header 來提交認證的，則回應必須用 401 加上 WWW-Authenticate ，其 value 要符合 Client 使用的 auth scheme （如 Bearer）

與 Authorization Endpoint 的差別：

• 多了 invalid_client ，因為有 Client 認證這個動作，而 Authorization Endpoint 則沒有。
• 多了 invalid_grant ，顯然，因為有傳 Grant 進來。
• 沒有 unsupported_response_type ，多了 unsupported_grant_type ，顯然，理由同上。
• 沒有 server_error 和 temporarily_unavailable ， Authorization Endpoint 會有，是因為 5xx 沒辦法轉址，而那個 Endpoint 需要轉址。在 Token Endpoint 沒有轉址的動作，所以不需要特別定義這兩個 error code 來提示伺服器錯誤，直接噴 5xx 就行了。（這是我個人的理解，不是寫在 spec 裡面）

範例

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "error":"invalid_request"
}

OAuth 2.0 系列文目錄

• (1) 世界觀
• (2) Client 的註冊與認證
• (3) Endpoints 的規格
• (4.1) Authorization Code Grant Flow 細節
• (4.2) Implicit Grant Flow 細節
• (4.3) Resource Owner Credentials Grant Flow 細節
• (4.4) Client Credentials Grant Flow 細節
• (5) 核發與換發 Access Token ← You Are Here
• (6) Bearer Token 的使用方法
• (7) 安全性問題
• 各大網站 OAuth 2.0 實作差異

如果是以下情況的話，就可以使用這個流程：

• Client 自己就是 Resource Owner ，Client 取用的是自己擁有的 Protected Resources
• Client is requesting access to protected resources based on an authorization previously arranged with the authorization server. （這個我看不懂，所以保留原文，求解釋…）

這個流程只能用在 Confidential Client 。

這是 OAuth 2.0 內建的四個流程之一。相對於別的流程來說簡單很多。本文整理自 Section 4.4。

流程圖

+---------+                                  +---------------+
|         |                                  |               |
|         |>--(A)- Client Authentication --->| Authorization |
| Client  |                                  |     Server    |
|         |<--(B)---- Access Token ---------<|               |
|         |                                  |               |
+---------+                                  +---------------+

                Figure 6: Client Credentials Flow

(A) Client 向 Authorization Server 認證自己，並且發 Request 到 Token Endpoint

(B) Authorization Server 認證 Client ，如果正確的話，核發 Access Token。

(A) Access Token Request

【Client】POST ▶ 【Token Endpoint】

參數

Authorization Server 的處理程序

這個 Request 進來的時候， Authorization Server 必須認證 Client，細節見系列文第 2 篇。（跟 Authorization Code Grant Type / Resource Owner Credentials Grant Type 不同，這個強制要求認證）

範例

POST /token HTTP/1.1
Host: server.example.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials

(B) Access Token Response

【Client】 ◀ 【Token Endpoint】

若 Access Token Request 合法且有經過授權，則核發 Access Token，但是最好不要核發 Refresh Token。如果 Client 認證失敗，或 Request 不合法，則依照 Section 5.2 的規定回覆錯誤。

詳細核發 Access Token 的細節寫在系列文第 5 篇。

（除了「建議不要發 Refresh Token」這一點之外，大致上同 Authorization Code Grant Flow。）

範例

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "access_token":"2YotnFZFEjr1zCsicMWpAA",
  "token_type":"example",
  "expires_in":3600,
  "example_parameter":"example_value"
}

OAuth 2.0 系列文目錄

• (1) 世界觀
• (2) Client 的註冊與認證
• (3) Endpoints 的規格
• (4.1) Authorization Code Grant Flow 細節
• (4.2) Implicit Grant Flow 細節
• (4.3) Resource Owner Credentials Grant Flow 細節
• (4.4) Client Credentials Grant Flow 細節 ← You Are Here
• (5) 核發與換發 Access Token
• (6) Bearer Token 的使用方法
• (7) 安全性問題
• 各大網站 OAuth 2.0 實作差異

• Resource Owner 高度信賴 Client ，例如作業系統內建的應用程式（好比說 OS X 的 Twitter 整合）或是官方應用程式。
• 其他別的流程都不適用。

而就算 Client 可以直接拿到 Resource Owner 的帳號密碼，也只會使用一次，用來取得 Access Token 。Spec 裡面定義的流程，會要求 Client 不儲存帳號密碼，而是隨後以長時效的 Access Token 或 Refresh Token 取代之。

Authorization Server 應該要特別小心開放這種流程，並且要在別的流程都行不通的時候才使用這種。

這種流程適用於可以取得 Resource Owner 帳號密碼的 Client （通常是透過一個輸入框）。也可以用來把以前的帳號密碼認證，遷移到 OAuth 認證。

最後拿到的除了 Access Token 之外，還會拿到 Refresh Token （Authorization Server 有支援的話）。

這是 OAuth 2.0 內建的四個流程之一。本文整理自 Section 4.3。

流程圖

+----------+
| Resource |
|  Owner   |
|          |
+----------+
     v
     |    Resource Owner
    (A) Password Credentials
     |
     v
+---------+                                  +---------------+
|         |>--(B)---- Resource Owner ------->|               |
|         |         Password Credentials     | Authorization |
| Client  |                                  |     Server    |
|         |<--(C)---- Access Token ---------<|               |
|         |    (w/ Optional Refresh Token)   |               |
+---------+                                  +---------------+

       Figure 5: Resource Owner Password Credentials Flow

(A) Resource Owner 向 Client 提供真正的帳號密碼。

(B) Client 用 Resource Owner 的帳號密碼，向 Authorization Server 的 Token Endpoint 申請 Access Token。這個時候 Client 還要向 Authorization Server 認證自己。

(C) Authorization Server 認證 Client 、驗證 Resource Owner 的帳號密碼，如果正確的話，核發 Access Token。

(A) Authorization Request & Response

在這個流程裡面， Authorization Grant 就是 Resource Owner 的帳號密碼，所以在 Step (A) 裡面直接向 Resource Onwer 索取，沒有經過網路來取得 Authorization。

Spec 不規定 Client 要怎麼拿到帳號密碼，但是 Client 取得 Access Token 之後，必須把 Resource Owner 的帳號密碼給銷毀掉。

(B) Access Token Request

【Client】POST ▶ 【Token Endpoint】

參數

Authorization Server 的處理程序

這個 Request 進來的時候， Authorization Server 要做這些事：

1. 要求 Client 認證自己（如果是 Confidential Client 或有拿到 Client Credentials）

• 如果 Client 有出示認證資料，就認證它，細節見系列文第 2 篇
• 驗證 Resource Owner 的帳號密碼（以既有的驗證方式）

慎防暴力破解

因為牽涉到帳號密碼，所以 Authorization Server 要可以防 Endpoint 被暴力破解，具體實施的方法像是 Rate Limiting 或是發出警告。

範例

POST /token HTTP/1.1
Host: server.example.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=password&username=johndoe&password=A3ddj3w

(C) Access Token Response

（同 Authorization Code Grant Flow。）

【Client】 ◀ 【Token Endpoint】

若 Access Token Request 合法且有經過授權，則核發 Access Token，同時可以核發 Refresh Token （非必備）。如果 Client 認證失敗，或 Request 不合法，則依照 Section 5.2 的規定回覆錯誤。

詳細核發 Access Token 的細節寫在系列文第 5 篇。

範例

發給 Access Token：

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "access_token":"2YotnFZFEjr1zCsicMWpAA",
  "token_type":"example",
  "expires_in":3600,
  "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
  "example_parameter":"example_value"
}

安全性問題 (Section 10.7)

帳號密碼外洩

Resource Owner Password Credentials Grant Type 通常是用在老舊 Client ，或是遷移舊的認證機制到 OAuth。雖然這種流程降低了在 Client 裡面儲存帳號密碼所引來的風險，但是沒有消除把帳號密碼給 Client 看的必要性。（編按：第一步還是需要 Resonrce Owner 提供帳號密碼）

這個流程的風險比起其他流程還要高，因為它保留了使用密碼的 anti-pattern，而這個卻是 OAuth spec 致力避免的。Client 可能會濫用密碼，或是密碼會不經意地洩漏給壞人（例如 Log 或是其他 Client 保存的記錄）。

Resource Owner 無法控制授權權限與存取範圍

此外，因為 Resource Owner 沒辦法控制授權的流程（Resource Owner 只參與到輸入帳號密碼），Client 可以取得比 Resource Owner 期望的權限 (scopes) 還要更多的權限。Authorization Server 在透過這種流程合法 Access Token 的時候應該要慎重考慮 scope 和時效的問題。

Authorization Server 和 Client 應該要儘量不使用這種流程，改用其他流程。

OAuth 2.0 系列文目錄

• (1) 世界觀
• (2) Client 的註冊與認證
• (3) Endpoints 的規格
• (4.1) Authorization Code Grant Flow 細節
• (4.2) Implicit Grant Flow 細節
• (4.3) Resource Owner Credentials Grant Flow 細節 ← You Are Here
• (4.4) Client Credentials Grant Flow 細節
• (5) 核發與換發 Access Token
• (6) Bearer Token 的使用方法
• (7) 安全性問題
• 各大網站 OAuth 2.0 實作差異

Authorization Server 核發 Access Token 的時候，不認證 Client （其實也無法認證），在某些情況下，可以用 Redirection URI 來確保 Access Token 只發給正確的 Client 。這種流程依賴 Resource Owner 本人的存在，以及事先設定的 Redirection URI。

這種流程是專門為特定的 Public Client 來優化的，例如跑在 Browser 裡面的應用程式。但也因此有外洩風險，例如：

• Resource Owner 可以看到 Access Token
• 其他可以存取 User-Agent 的應用程式，也可以看到 Access Token
• Access Token 傳輸時，會直接出現在 Redirection URI 裡面，所以 Resource Owner 以及同一台設備的應用程式可以看到

因為需要實施轉址，所以 Client 要可以跟 Resource Owner 的 User-Agent (Browser) 互動，也要可以接收從 Authorization Server 來的 Redirection Request。（同 Authorization Code Grant Flow）

最後拿到的只有 Access Token ，不會拿到 Refresh Token （禁止核發 Refresh Token）。

這是 OAuth 2.0 內建的四個流程之一。本文整理自 Section 4.2。

流程圖

+----------+
| Resource |
|  Owner   |
|          |
+----------+
     ^
     |
    (B)
+----|-----+          Client Identifier     +---------------+
|         -+----(A)-- & Redirection URI --->|               |
|  User-   |                                | Authorization |
|  Agent  -|----(B)-- User authenticates -->|     Server    |
|          |                                |               |
|          |<---(C)--- Redirection URI ----<|               |
|          |          with Access Token     +---------------+
|          |            in Fragment
|          |                                +---------------+
|          |----(D)--- Redirection URI ---->|   Web-Hosted  |
|          |          without Fragment      |     Client    |
|          |                                |    Resource   |
|     (F)  |<---(E)------- Script ---------<|               |
|          |                                +---------------+
+-|--------+
  |    |
 (A)  (G) Access Token
  |    |
  ^    v
+---------+
|         |
|  Client |
|         |
+---------+

註: (A), (B) 這兩步的線拆成兩段，因為會經過 user-agent

                    Figure 4: Implicit Grant Flow

(A) Client 把 Resource Owner 的 User-Agent 轉到 Authorization Endpoint 來啟動流程。Client 會傳送：

• Client ID
• 申請的 scopes
• 內部 state
• Redirection URI，申請結果下來之後 Authorization Server 要轉址過去。

(B) Authorization Server 通過 User-Agent 認證 Resource Owner，並確定 Resource Onwer 許可或駁回Client 的存取申請。

(C) 假設 Resource Owner 許可了存取申請， Authorization Server 會把 User-Agent 轉回去先前指定的 Redirection URI ，其中包含 Access Token ，放在 Fragment Component 裡面。

(D) User-Agent 跟隨轉址的指示，發出 Request 到 Web-Hosted Client Resource ，這個 Request 裡面不會有剛剛拿到的 Fragment ， User-Agent 自己保留 Fragment 。（註）

(E) Web-Hosted Client Resource 回傳一個網頁（HTML & JavaScript），這個網頁可以拿到完整的 Redirection URI （含先前 User-Agent 保留的 Fragment）、把 Fragment 裡面的 Access Token 和其他參數給解出來。（註）

(F) User-Agent 執行從 Web-Hosted Client Resource 來的 Script 把 Access Token 解出來。

(G) User-Agent 把 Access Token 傳給 Client。

註： (D) 之後的有點抽象，我的理解是這樣：

• Web-Hosted Client Resource 當作你自己架的 App Server ，在上面開 Redirection Endpoint ，所以這個流程其實 Client 本體 (JavaScript App) 沒有 Endpoint ，Endpoint 是開在一個 HTTP(s) Server 上面。
• Browser 事實上在 Access http://example.com/cb#access_token=123 的時候，只會發送 http://example.com/cb 的 request ，在 Request 裡面不會有 #access_token=123
• 所以 (D) 所謂「Request 不含 Fragment，User-Agent 自己保留 Fragment」這一步是 User-Agent 自動做的， Client 開發者不需要用 JavaScript 特別處理，只要把 Redirection Endpoint 指定給自己的 App Server 就可以了。
• 而 (E) 所謂「回傳一個網頁來解出 User-Agent 保留的 Fragment」，就是說 User-Agent 打 Request 到 Redirection URI （含 Fragment，但不會傳送到 Server）的時候，他的 response 裡面包含 JavaScript ，而上面說了，Fragment 是自動保留在 User-Agent 的，所以這個 Response 在 Server 那邊不會知道有 Fragment 的存在，也就不會知道 Access Token 的存在，而是 User-Agent 才知道。
• 所以 (F) 就是跑這個 script 解出 Access Token 和參數，(G) 把 (F) 的執行結果塞給 Client (JavaScript App)。

也就是說其實是設計給不能聽 Redirection Endpoint 的 In-Browser JavaScript App 的解法。我看到的用法是 Google 的 OAuth 2.0 for Client-side JavaScript。

(A) Authorization Request

【User-Agent】GET ▶【Authorization Endpoint】

第一步是 Client 產生一個 URL 連到 Authorization Endpoint ，要 Resource Owner 打開（點擊）這個 URL ，從而產生「向 Authorization Endpoint 發送 GET request」的操作。

把參數包在 URI 的 query component 裡面。

參數

其中的 state， Authorization Server 轉回 Client 的時候會附上。可以防範 CSRF ，所以最好是加上這個值，詳見系列文第 7 篇關於 CSRF 的安全性問題。

Authorization Server 的處理程序

因為 Implicit Grant Flow 是直接在 Authorization Endpoint 發 Access Token ，所以資料驗證和授權都在這一步處理。所以這個 Request 進來的時候， Authorization Server 要做這些事：

1. 驗證所有必須給的參數都有給且合法

• Redirection URI 與預先在 Authorization Server 設定的相符。

如果沒問題，就詢問 Resource Owner 是否授權，即 (B) 步驟。

(C) Authorization Response

【Client】 ◀ 302【Authorization Endpoint】

是 Resource Owner 在 (B) 決定授權與否之後回應的 Response。

在 (B) 裡面， Resource Owner 若同意授權，這個「同意授權」的 request 會往 Authorization Endpoint 發送，接著會收到 302 的轉址 response ，裡面帶有「前往 Client 的 Redirection Endpoint 的 URL」的轉址 (Location header)，從而產生「向 Redirection URI 發送 GET Request」的操作。

參數要用 URL Encoding 編起來，放在 Fragment Component 裡面。

若 Access Token Request 合法且有經過授權，則核發 Access Token。如果 Client 認證失敗，或 Request 不合法，則依照 Section 5.2 的規定回覆錯誤。

特別注意 Implicit Grant Type 禁止 核發 Refresh Token。

某些 User-Agent 不支援 Fragment Redirection ，這種情況可以使用間接轉址，即是轉到一個頁面，放一個 "Continue" 的按鈕，按下去連到真正的 Redirection URI 。

參數

其中 scope 如果和 (A) 申請的不同則要附上，如果一樣的話就不必附上。

其中 state 如果 (A) 的時候有附上，則 Resopnse 裡面必須有，完全一致的原值。如果原本就沒有，就不需要回傳。

Access Token 的長度由 Authorization Server 定義，應寫在文件中， Client 不可以瞎猜。

Client 遇到不認識的參數必須忽略。

範例

HTTP/1.1 302 Found
Location: http://example.com/cb#access_token=2YotnFZFEjr1zCsicMWpAA
          &state=xyz&token_type=example&expires_in=3600

錯誤發生時的處理方式

跟 Authorization Code Grant Flow 相同，差別在於錯誤的內容是放在 Fragment Component 而不是 Query Component。請參考系列文第 4.1 篇關於 Authorization Code Grant Flow 的 Access Token Request 錯誤處理原則。

例如：

HTTP/1.1 302 Found
Location: https://client.example.com/cb#error=access_denied&state=xyz

安全性問題

在 spec 裡面提及的安全性問題寫在 Section 10.3 和 10.16 ，其中 10.3 只是特別提到 Implicit Grant Type 「透過 URI Fragment 來傳 Access Token ，所以可能會外洩」，而 10.16 則是針對 Implicit Grant Type 可能會有偽造 Resource Owner 的安全性問題。其中 10.3 關於 Access Token 保密的問題，見系列文第 7 篇。

誤用 Access Token 來在 Implicit Flow 裡面偽裝 Resource Owner (Section 10.16)

這個 Section 的原文我看不太懂，似乎是在說，這流程裡面會有漏洞讓壞人可以置換 Access Token ，原本是要給 A Client 的 Token 到了 B Client 的手上。Amazon 的文件 裡面有提到，他的建議是，在真的拿 Token 來用之前，要去 Authorization Server 問一下是不是真是給這個 Client 用的，不是的話就不能用。

新浪微博 API 的「用户身份伪造」應該也是在講類似的事。

OAuth 2.0 系列文目錄

• (1) 世界觀
• (2) Client 的註冊與認證
• (3) Endpoints 的規格
• (4.1) Authorization Code Grant Flow 細節
• (4.2) Implicit Grant Flow 細節 ← You Are Here
• (4.3) Resource Owner Credentials Grant Flow 細節
• (4.4) Client Credentials Grant Flow 細節
• (5) 核發與換發 Access Token
• (6) Bearer Token 的使用方法
• (7) 安全性問題
• 各大網站 OAuth 2.0 實作差異

在這種流程裡， Authorization Grant Code 會以一個字串 (string) 具體存在，並且傳遞給 Client ，做為 Authorization Grant （Resource Owner 的授權許可）。在取得 Grant 之後，還沒有取得 Access Token ，Client 要再自己去向 Authorization Server 取得 Access Token 。

這個流程是專門為在 Server 執行的 Confidential Client 優化的。

因為需要實施轉址，所以 Client 要可以跟 Resource Owner 的 User-Agent (Browser) 互動，也要可以接收從 Authorization Server 來的 Redirection Request。

最後拿到的除了 Access Token 之外，還會拿到 Refresh Token （Authorization Server 有支援的話）。

這是 OAuth 2.0 內建的四個流程之一。本文整理自 Section 4.1。

流程圖

+----------+
| Resource |
|   Owner  |
|          |
+----------+
     ^
     |
    (B)
+----|-----+          Client Identifier      +---------------+
|         -+----(A)-- & Redirection URI ---->|               |
|  User-   |                                 | Authorization |
|  Agent  -+----(B)-- User authenticates --->|     Server    |
|          |                                 |               |
|         -+----(C)-- Authorization Code ---<|               |
+-|----|---+                                 +---------------+
  |    |                                         ^      v
 (A)  (C)                                        |      |
  |    |                                         |      |
  ^    v                                         |      |
+---------+                                      |      |
|         |>---(D)-- Authorization Code ---------'      |
|  Client |          & Redirection URI                  |
|         |                                             |
|         |<---(E)----- Access Token -------------------'
+---------+       (w/ Optional Refresh Token)

註: (A), (B), (C) 這三步的線拆成兩段，因為會經過 user-agent

                  Figure 3: Authorization Code Flow

(A) Client 把 Resource Owner 的 User-Agent 轉到 Authorization Endpoint 來啟動流程。Client 會傳送：

• Client ID
• 申請的 scopes
• 內部 state
• Redirection URI，申請結果下來之後 Authorization Server 要轉址過去。

(B) Authorization Server 通過 User-Agent 認證 Resource Owner，並確定 Resource Onwer 許可或駁回Client 的存取申請。

(C) 假設 Resource Owner 許可了存取申請， Authorization Server 會把 User-Agent 轉回去先前指定的 Redirection URI ，其中包含了：

• Authorization Code
• 許可的 scopes （如果跟申請的不一樣才會附上）
• 先前提供的內部 state （原封不動，如果先前有提供才會附上）

(D) Client 向 Authorization Server 的 Token Endpoint 要求 Access Token，申請時會傳送：

• 先前取得的 Authorization Code
• Redirection URI，用來驗證和之前 (C) 時的一致。
• Client 的認證資料

(E) Authorization Server 認證 Client 、驗證 Authorization Code、並確認 Redirection URI 和之前 (C) 轉址的一致。都符合的話，Authorization Server 會回傳 Access Token ，以及可選的 Refresh Token。

(A) Authorization Request

【User-Agent】GET ▶【Authorization Endpoint】

第一步是 Client 產生一個 URL 連到 Authorization Endpoint ，要 Resource Owner 打開（點擊）這個 URL ，從而產生「向 Authorization Endpoint 發送 GET request」的操作。

把參數包在 URI 的 query components 裡面。

參數

其中的 state， Authorization Server 轉回 Client 的時候會附上。可以防範 CSRF ，所以最好是加上這個值，詳見系列文第 7 篇關於 CSRF 的安全性問題。

範例

GET /authorize?response_type=code&client_id=s6BhdRkqt3&state=xyz
    &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1
Host: server.example.com

(C) Authorization Response

【Authorization Endpoint】 302 Response ▷ 【User-Agent】▶ GET 【Client: Redirection Endpoint】

是 Resource Owner 在 (B) 決定授權與否之後回應的 Response。

在 (B) 裡面， Resource Owner 若同意授權，這個「同意授權」的 request 會往 Authorization Endpoint 發送，接著會收到 302 的轉址 response ，裡面帶有「前往 Client 的 Redirection Endpoint 的 URL」的轉址 (Location header)，從而產生「向 Redirection URI 發送 GET Request」的操作。

參數

其中 state 如果 (A) 的時候有附上，則 Resopnse 裡面必須有，完全一致的原值。如果原本就沒有，就不需要回傳。

其中 Authorization Code：

• 必須是短時效的，建議最長 10 分鐘。
• Client 只能使用一次，如果重複使用，Authorization Server 必須拒絕，並且建議撤銷之前透過這個 Grant 核發過的 Tokens
• 要綁定 Code ↔ Client ID ↔ Redirection URI 的關係
• 長度由 Authorization Server 定義，應寫在文件中， Client 不可以瞎猜。

Client 遇到不認識的參數必須忽略。

範例

HTTP/1.1 302 Found
Location: https://client.example.com/cb?code=SplxlOBeZQQYbYS6WxSbIA
          &state=xyz

錯誤發生時的回應方式

如果發生的錯誤是：

• Redirection URI 沒給、不正確、沒註冊過
• Client ID 沒給、不正確

則 Authorization Server 應該告知 Resource Owner 這個錯誤，並且絕對不可以自動轉址到錯誤的 Redirection URI。

如果發生的錯誤是因為 Resource Owner 拒絕授權或是因為除了 Redirection URI 不正確的原因，那麼 Authorization Server 要告知 Client ，方法是把錯誤內容放在 Redireciton URI 的 Query Component 裡面，用 URL Encoding 編碼過，可用的參數為：

其中 state 如果 (A) 的時候有附上，則 Resopnse 裡面必須有，完全一致的原值。如果原本就沒有，就不需要回傳。

而 error 的值是以下的其中一個：

其中 server_error 和 temporarily_unavailable 有必要，因為 5xx 系列的 status code 不能轉址。

(D) Access Token Request

【Client】POST ▶ 【Token Endpoint】

參數

其中 client_id 只有 Public Client 才需要提供，如果是 Confidential Client 或有拿到 Client Credentials ，就必須進行 Client 認證，細節見系列文第 2 篇。

Authorization Server 的處理程序

這個 Request 進來的時候， Authorization Server 要做這些事：

1. 要求 Client 認證自己（如果是 Confidential Client 或有拿到 Client Credentials）

• 如果 Client 有出示認證資料，就認證它，細節見系列文第 2 篇
• 確定 Authorization Code 是發給 Client 的
  • Confidential: 用 Client 的認證過程來證明
  • Public: 用 Client ID 來證明
• 驗證 Authorization Code 正確
• 如果 (A) 有給 Redirection URI 的話，確定這次給的 Redirection URI 與 (A) 時的一模一樣。

範例

POST /token HTTP/1.1
Host: server.example.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA
&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb

(E) Access Token Response

【Client】 ◀ 【Token Endpoint】

若 Access Token Request 合法且有經過授權，則核發 Access Token，同時可以核發 Refresh Token （非必備）。如果 Client 認證失敗，或 Request 不合法，則依照 Section 5.2 的規定回覆錯誤。

詳細核發 Access Token 的細節寫在系列文第 5 篇。

範例

發給 Access Token：

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "access_token":"2YotnFZFEjr1zCsicMWpAA",
  "token_type":"example",
  "expires_in":3600,
  "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
  "example_parameter":"example_value"
}

安全性問題

Authorization Code 的安全性問題 (Section 10.5)

Authorization Code 被偷

Authorization Code 的傳輸應該要經由安全通道，特別是如果 Client 的 Redirection URI 是指向網路資源（根據 scheme），那麼應該要求其使用 TLS。

另外，因為 Authorization Code 是經由 User-Agent 的轉址來傳輸的，所以可能從 User-Agent 的歷史記錄和 Referrer header 裡面找到。

從 Authorization Code 來認證 Reosurce Owner

Authorization Code 做為一個純文字的 bearer credential （代表持有者的 credential）來運作，這個 credential 用來驗證：在 Authorization Server 上面授予權限的 Resource Owner = 返回 Client 要完成程序的 Resource Owner。所以，如果 Client 依賴予 Authorization Code 來認證 Resource Owner ，那麼 Client 端的 Redirection Endpoint 必須使用 TLS。

Authorization Code 被二度利用

Authorization Code 必須要是短時效、單次使用。如果 Authorization Server 檢測到多次的請求來把一個 Authorization Code 換成 Access Token ，那麼 Authorization Server 應該要試著撤銷所有之前使用該 Authrization Code 來取得的 Access Token 。

認證 Client 防止誤發 Authorization Code

如果對 Client 的認證可行，那麼 Authorization Server 必須認證該 Client ，並且確保 Authorization Code 核發給同一個 Client 。

竄改 Authorization Code 的 Redirection URI (Section 10.6)

使用 Authorization Code Grant Type 要求授權的時候，Client 可以用 "redirect_uri" 來指定 Redirection URI。如果壞人可以竄改 Redirection URI 的值，他就可以讓 Authorization Server 把 Resource Owner 轉向到壞人控制的 URI ，並且拿到 Authorization Code。

步驟如下：

1. 壞人在合法的 Client 建立一個帳號，並起始授權流程。

• 當壞人的 User-Agent 被傳送到 Authorization Server 來取得存取權限的時候，壞人取得由 Client 提供的 Authorization URI 並且把 Client 的 Redirection URI 取代成壞人控制的 URI。
• 壞人接著晃點 (trick) 受害者去跟隨修改過的連結來授權合法 Client 的存取權限。
• 在 Authorization Server，受害者會得到一個正常的、正確的 Request ，其 Request 代表合法的、受信任的 Client，並且授權其存取。
• 受害者接著會被轉向壞人控制的 Endpoint ，還附上 Authorization Code。
• 壞人接著把 Authorization Code 送到原先 Client 提供的真正的 Redirection URI 來完成授權流程。
• Client 把 Authorization Code 換成 Access Token 並且連結到壞人的帳號，而這個 Access Token 可以用來透過 Client 存取受害者的 Protected Resource 。

防範方式：

確認 Redirection URI 一致 ：Authorization Server 必須確保之前用來拿取 Authorization Code 的 Redirection URI ，跟之後透過 Authorization Code 拿取 Access Token 時的 Redirection URI 一模一樣。

事先設定 Redirection URI 並驗證 ：Authorization Server 必須要求 Public Clients 並且最好要要求 Confidential Clients 事先指定 Redirection URIs。如果有一個 Redirection URI 附在 request 裡面，那麼 Authorization Server 必須驗證其符合事先指定的 URIs。

OAuth 2.0 系列文目錄

• (1) 世界觀
• (2) Client 的註冊與認證
• (3) Endpoints 的規格
• (4.1) Authorization Code Grant Flow 細節 ← You Are Here
• (4.2) Implicit Grant Flow 細節
• (4.3) Resource Owner Credentials Grant Flow 細節
• (4.4) Client Credentials Grant Flow 細節
• (5) 核發與換發 Access Token
• (6) Bearer Token 的使用方法
• (7) 安全性問題
• 各大網站 OAuth 2.0 實作差異

• Authorization Server 的 Authorization Endpoint
• Client 的 Redirection Endpoint
• Authorization Server 的 Token Endpoint

其規格如下文，不能只看名稱來判別其用途，像是 Authorization Endpoint 其實是一點多用，在某些流程裡會發 Authorization Grant Code ，有些流程會直接發 Access Token ，有些流程會略過之。

使用的順序大致上是 Authorization Endpoint → Redirection Endpoint → Token Endpoint 。

可以發現到 Resource Server 上面並沒有定義任何 Endpoints ，這是因為取得 Access Token 的流程與 Resource Server 無關， Resource Server 只需要認 Access Token 並且向 Authorization Server 驗證 Token 合法就行了。

Authorization Endpoint (Authorization Server)

Authorization Endpoint 主要是給 Client 從 Resource Owner 取得 Authorization Grant 用的，其過程會透過 User-Agent 轉向。

在內建的四種流程中，只有 Authorization Code Grant Flow 和 Implicit Grant Flow 才會使用到。

處理過程中，必須先認證 Resource Owner ，但認證方法在 spec 裡面不明確定義，或許是帳密、或許是 session cookie 。也就是說要登入這個使用者。

Client 得知 Authorization Endpoint 的方法不定義，通常是直接寫在服務的文件裡面。

URI 要求

• URI 裡面可以有 Query Component（如 ?xxx=yyy），但是當要加入其他 parameter 的時候，必須保留既有的 parameters 。
• URI 裡面不可以有 Fragment Component （#zzz）。

HTTP Method

必須支援 GET。可以支援 POST（非必備）。

傳遞的參數

Response Type

Response Type 透過 response_type 參數來指定，其值定義如下：

若 response_type 欠缺或認不得，必須回錯誤，見下文。

參數解析原則

• 留空的參數要當做沒有提供 (omitted) 。例如 response_type=code&state= 要當做沒給 state 參數。
• 認不得的參數必須忽略之。
• 每個參數只能出現一次，不可重覆出現。若有重覆，則要回傳錯誤。

TLS (https) 要求

必須經過 TLS ，因為 response 裡面有 credentials 會被看到。

遇到錯誤的時候的處理方式

所謂錯誤，像是參數錯誤、Client 不被授權使用這種 Authorization 、Server 不支援這種 Authorization 等等。雖然 Spec 裡面的四種流程，有用到 Authorization Endpoint 的（其實就是 Authorization Code 和 Implicit），其處理方式都一樣，但是只使用於內建流程， Extension 可能會使用更多的，所以不寫在這篇裡面。

你只要知道 spec 裡面的內建流程，對於 Authorization Endpoint 的錯誤處理方式是一模一樣的就好了。

Section 3.1, 3.1.1

Redirection Endpoint (Client)

Authorization Server 在完成與 Resource Owner 的互動之後（認證 Resource Owner 、提示 Client 要請求授權之類的），會把 Resource Owner 的 User-Agent 轉回 Cilent ，這個轉回去的目標就是 Redirection Endopoint 。

在內建的四種流程中，只有 Authorization Code Flow 和 Implicit Flow 才會使用到。

註：本文省略關於多重 Redirection URI 和動態設置 (Dynamic Configuration) 的 spec 的解說，因為一來我看不懂，二來我沒用過要指定多個 Redirection URI 的 OAuth 服務，所以不清楚它的用途，我想對於入門來說應該是不需要說明（我也沒能力說明）。有興趣的同學可以看 spec 的 Section 3.1.2.3 。

Client 設定 Redirection Endpoint

Redirection Endpoint 可以在 Client 註冊的時候設定，或是在發出 Authorization Request 的時候指定。

以下這些類型的 Clients 必須設定 Redirection Endpoint：

• Public Client
• Confidential Client 且利用 Implicit Grant Type

Authorization Server 應該要要求所有 Clients 在使用 Authorization Endpoint 之前，都設定 Redirection Endpoint。會要求設定 Redirection Endpoint，是為了防止壞人利用 Authorization Endopint 做為 open redirector 。詳見本文最末段，關於安全性的問題。

Authorize 時，Redirection URI 不正確的處理方式

如果 Authorization Server 驗證 Redirection URI 失敗（沒註冊、不相符等情況），則 Authorization Server 應該提示錯誤，並且 不可以自動轉回 錯誤的 Redirection URI 。

URI 的要求

• 必須是 Absolute URI （就是下圖的 scheme + hierarchical + query (選用)）。定義在 RFC3986 的 Section 4.3。
• URI 裡面可以有 Query Component（如 ?xxx=yyy），但是當要加入其他 parameter 的時候，必須保留既有的 parameters 。
• URI 裡面不可以有 Fragment Component （#zzz）。

若無法指定完整的 URI （像是不能指定 Query Component），則應該要求指定 URI 的 scheme 、 authority 、 path 這三個部份（見下圖）。

就我的理解可以給出以下範例：

根據維基百科的解釋，即是 Query Component 之前的所有部份，亦即僅允許 Client 自訂 Query Component：

  foo://username:password@example.com:8042/over/there/index.dtb?type=animal&name=narwhal#nose
  \_/   \_______________/ \_________/ \__/            \___/ \_/ \______________________/ \__/
   |           |               |       |                |    |            |                |
   |       userinfo         hostname  port              |    |          query          fragment
   |    \________________________________/\_____________|____|/ \__/        \__/
   |                    |                          |    |    |    |          |
scheme              authority                    path   |    |    interpretable as keys
 name   \_______________________________________________|____|/       \____/     \_____/
                             |                          |    |          |           |
                     hierarchical part                  |    |    interpretable as values
                                                        |    |
                                interpretable as filename    interpretable as extension

TLS (HTTPS) 的要求

Redirection Endpoint 在以下任一種情況，應該要有 TLS ：

• 發出 Authorization Request 時的 Response Type 為 code 或 token （= 內建流程的每一種）。
• 重新轉向的時候會經由公開網路傳遞敏感資料。

然而這個並不強求，因為現階段有些 Client 實作 TLS 有困難。因此，若重新轉向的目標並不是 TLS (https) ，則 Authorization Server 應該要向 Resource Owner 提出警告。

關於 Redirection Endpoint 的內容的建議

所謂的內容，就是當 User-Agent 打開 Redirection Endpoint URI 的時候看到的內容，通常是 HTML ，所以如果 HTML 直接在 Redirection Request 輸出的話，任何 script 都可以拿到 Redirection URI 及包含在其中的 credentials 。

因此有這些建議：

• Client 應該直接從 URI 裡面解出 credentials ，並且馬上 redirect 到別的地方以防外洩。
• Client 不應該在 Redirection Response 裡面載入第三方 script （Analytics 、社交網站、廣告等）。
• 若第三方 script 無法避免，則 Client 必須確保自己的 script 先跑，先把 credentials 解出來，並且移除 credentials 。

從 Rails 的實作方式來說，就是直接在 Controller 裡面解出 credentials ，存進 Model ，然後 redirect 到別的 path 就行了。

Section 3.1.2 - 3.1.2.5

Token Endpoint (Authorization Server)

Token Endpoint 是 Client 用來拿取 Access Token 的。拿取的時候，要出示 Authorization Grant （第一次拿 Access Token）或 Refresh Token （舊的 Access Token 不能用，要重新拿新的）。

在內建的四種流程裡，只有 Implicit Grant Type 不使用之，因為這個流程的 Access Token 是直接在 Authorization Endpoint 那邊就直接給了。

在 Token Endpoint 處理的流程中，有一步是認證 Client ，用來確認 Client 的身份。詳見「關於認證 Client 的說明」一段。

Client 得知 Token Endpoint 的方法不定義，通常是直接寫在服務的文件裡面。（同 Authorization Endpoint）

HTTP Method

必須使用 POST。Client 在發送 Token Request 的時候，也必須使用 POST 。

URI 要求

（同 Authorization Endpoint）

• URI 裡面可以有 Query Component（如 ?xxx=yyy），但是當要加入其他 parameter 的時候，必須保留既有的 parameters 。
• URI 裡面不可以有 Fragment Component （#zzz）。

傳遞的參數

雖然在 Token Endpoint 的 Spec 裡面沒有寫到必備的參數，但我整理了四種內建流程以及換發 Token 的流程之後，總結出「一定要有 Grant Type」這個事實，所以在這裡寫下來。還有其他參數，但是會根據流程的不同而不同。

Grant Type

Grant Type 透過 grant_type 參數來指定，其值定義如下：

至於更多 Grant Types 可以參考 Section 8.3。

Grant Type 沒給，或不認得的時候，回應錯誤的方式見系列文第 5 篇。

參數解析原則

（同 Authorization Endpoint）

TLS (https) 要求

必須經過 TLS ，因為 request 和 response 裡面都有 credentials 會被看到。

Response 的方式

由於這個 Endpoint 是專門用來核發 Access Token 的，其 Response 的方式以及錯誤回應方式，我寫在系列文第 5 篇。

關於認證 Client 的說明

在 Token Endpoint 的流程裡面，有一步是要認證 Client ，需要認證的 Clients 是 Confidential Clients 或是有發給 Client Credentials 的 Clients 。

實際認證的機制，規定在 Section 2.3 裡面（系列文第 2 篇）。簡單來說，要用 HTTP Basic Auth 來認證，設 Client Credential 為：ID s6BhdRkqt3 、 Secret 7Fjfp0ZBr1KtDRbnfVdmIw ，那麼在 Client 往 Token Endpoint 發 Request 的時候， Request Header 裡面要有這個：

Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3

認證 Client 是為了：

• 強化「Refresh Token ↔ 核發的對象 Client」與「Authorization Code ↔ 授予的對象 Client」之間的關係。當 Authorization Code 要透過不安全通道傳到 Redirection Endpoint 的時候，或是 Redirection URI 沒有全部註冊的時候（動態組態，本文略），Client 認證就顯得很重要。
• 用來復原被駭掉的 Client ，做法是禁用或更改它的 Credentials ，這樣子可以防止壞人濫用被偷走的 Refresh Token。替換單獨一組 client credential 比撤銷整組 Refresh Tokens 還要來得快。
• 實施認證管理的最佳實踐 (Best Practice)，即是要求定期更換 credentials。更換所有的 Refresh Token 是很難做到的，而定期更換單獨一組 credential 卻很容易。

在某些流程裡，Client 會用 client_id 參數來識別自己。像是在 Authorization Code Grant 流程裡面，發 Request 到 Access Token 的時候，沒有認證的 Client （如 Public Client）就必須用 client_id 來避免收到給別的 Client 的 Access Token，Authorization Server 也可以藉此防止 Client 自己置換 Authorization Code。需注意這個方法並不會為 Proteected Resource 帶來額外的保護。

Section 3.2 - 3.2.1

Endpoints 通用的參數

scope: 指定存取範圍

Authorization Endpoint 和 Token Endpoint 允許 Client 指定申請 Access Token 的時候所要的 scopes （存取範圍）。

參數名稱是 scope。格式是一串 scopes 用空格 (U+0020) 分開，區分大小寫。每一個 scope 的值是由 Authorization Server 定義的，格式是 ASCII 可見字元，排除雙引號 " (U+0022) 和反斜線 \ (U+005C)。順序不重要。每出現一個 scope 值，就代表要多加一個新的 scope。

根據 Authorization Server 制定的政策，以及 Resource Owner 的指示，可以完全或部份忽略某些 scopes。在這種情況下，scope 值也會在 Endpoint Response 裡面回傳，也就是當真正授予的 scopes 與原本要求的不同的時候告訴 Client。所以可能比原本要求的 scopes 還要少，也可能還要多。

假如 Client 在申請 Authorization 的時候，沒有給 scope 值，則 Authorization Server 必須做以下之中的一件事：

• 用預設值處理（若有）。
• 回報錯誤，提示 scope 不合法。

處理方式、預設值、 scope 的要求，應該要寫在 Authorization Server 文件裡。

實務上的 scope

實務上大部份網站的 OAuth 2.0 實作方式， scope 都是用逗號 (,, U+002C) 分隔的，有的甚至不存在 scope 這種東西，一授權就是 full access。之後會寫一篇文章來整理。

Section 3.3

state: 維持 Endpoint 之間的操作狀態

Endpoint 之間可以用 state 參數來維持操作狀態，例如這種情況：

• 我打開 A 網站的 X 頁面
• 我按下「登入」按鈕來登入 A 網站，用 Facebook 帳號來登入
• Facebook 完成登入流程之後，回到 A 網站
• 我希望我看到的是 A 網站的 X 頁面←【目標】

要達到這個目標，就可以用 state 參數來維持「使用者之前在看 X 頁面」這個狀態。

state 參數在傳遞的過程中會原封不動，所以 Client 最後一定會得到原本的 state 。

又，因為 state 可能會放在 URI 裡面，所以如果裡面有敏感資料，則可能會留下痕跡（像是 Log 、 Proxy 的 Log 等等），所以最好是 Client 有內建加解密機制，這樣子在傳遞的過程就不會被抄走。

state 也可以應用在防止 CSRF ，見 Section 10.12 （系列文第 7 篇 ）。

安全性問題

Open Redirectors (Section 10.15)

Open Redirector 指的是 Endpoint 使用某參數來自動把 User-Agent 轉向到該參數所指定的位置，而沒有經過事先驗證。Auothorization Server 、 Authorization Endpoint 、 Client Redirection Endpoint 可能會因為設定的不好所以變成 Open Redirector。

Open Redirectors 會被利用在釣魚攻擊，或是讓壞人得以偽造 URI 的 authority part 讓它看起來很像可信任的網站，引導使用者前往惡意網站。此外，如果 Authorization Server 允許 Client 只事先指定 Redirection URI 的一部分，那麼壞人可以利用 Client 操作的 Open Redirector 來建立一個 Redirection URI ，這個 URI 跳過 Authorization Server 驗證，但是會把 Authorization Code 或 Access Token 傳送到壞人所控制的 endpoint。

在Amazon 的文件裡面，提出了 Open Redirector 常有的 pattern ：

• example.com/go.php?url=
• example.com/search?q=user+search+keywords&url=
• example.com/coupon.jsp?code=ABCDEF&url=
• example.com/login?url=

這種「疑似可以手動指定之後要再轉去別的地方」的參數容易變成 Open Redirector。

OAuth 2.0 系列文目錄

• (1) 世界觀
• (2) Client 的註冊與認證
• (3) Endpoints 的規格 ← You Are Here
• (4.1) Authorization Code Grant Flow 細節
• (4.2) Implicit Grant Flow 細節
• (4.3) Resource Owner Credentials Grant Flow 細節
• (4.4) Client Credentials Grant Flow 細節
• (5) 核發與換發 Access Token
• (6) Bearer Token 的使用方法
• (7) 安全性問題
• 各大網站 OAuth 2.0 實作差異

而認證 (Authentication) 的流程則是有規定需要傳送的資料。所謂的認證，就是 Client 要向 Authorization Server 證明自己的身份，若把 Client 比喻為人類使用者的話，就像是打帳號密碼之類的動作。在 spec 內建的流程中，需要認證 Client 的地方只有 Token Endpoint，就是「發給你 Token 的時候」認證。其中 Implicit Flow 並沒有認證 Client （也沒有經過 Token Endpoint）。

Client 的註冊

Spec 不規定 Client 如何向 Authorization Server 註冊自己，通常是用 HTML 界面。註冊時， Authorization Server 與 Client 之間不需要有直接互動，如果 Authorization Server 支援的話，註冊的過程可以依賴其他的手段來建立互相的信任、取得 Client 的註冊資料（Redirection URI 、Client Type 等）。例如，可以透過內部的通道來搜尋 Client 。

註冊的時候， Client 的開發人員應該要做這些事：

• 指定 Client Type （見下文）
• 指定 Redirection URL （如 Section 3.1.2 所述）
• 提供其他 Authorization Server 要求的資料（名稱、網站、Logo 等）

Section 2

Client Types

在 spec 裡面，根據有沒有能力保密 client 的 credentials （帳號密碼），定義了兩種 Client Types：

confidential：Client 可以自我保密 client 的 credentials（例如跑在 Server 上面，且可以限制 credentials 的存取），或是可以用別的手段來確保認證過程的安全性。

public：Client 無法保密 credentials （Native App 或是跑在 Browser 裡面的 App），或是無法用任何手段來保護 client 的認證。

Authorization Server 不應該自行猜測 Client 屬於何種。（不過現實卻不是這樣，見下文。）

單一的 Client 可能會分離成不同的組件 (components) ，如一個跑在 Server 、一個跑在 Client 。若 Authorization Server 沒有支援這種 Client ，或沒有指南文件，則開發人員時必須為各個組件註冊不同的 Clients。

Section 2.1

Client Profiles

OAuth 2.0 的 spec 是為以下這些類型的 Clients 來設計的：

Web Application：

• 屬於 confidential
• 跑在 Web Server 上面。
• Client Credentials 及 Access Token 儲存在 Server 上面，於 Resource Owner 不可見。

User-Agent-based Application

• 屬於 public
• Client 的程式是從 Web Server 下載到 Resource Owner 的 User-Agent 來執行的。
• 通訊協定過程的數據以及 credentials 可以很容易被 Resource Owner 取得（而且通常看得到）。
• 也因為這種 app 直接跑在 User-Agent 裡面，所以可以在取得 Authorizations 的時候無縫接軌。

Native Application

• 屬於 public
• 安裝在 Resource Owner 的設備上，也在其上執行。
• 通訊協定過程的數據與 credentials 可以被 Resource Owner 取得。
• 任何包在 app 裡面的 Client Credentials 都要假設可以被解出來。
• 相對而言，動態取得的 credentials ，像是 Access Token 、 Refresh Token ，可以得到某種程度的保護。至少，如果把這些 credentials 存放在 Client 會使用的伺服器上，也可以得到保護。
• 在某些平台上，這些 credentials 可能會被保護起來，從而不讓其他在同一台設備上的其他 apps 取得。（OS X 的 Keychain Access 就是這種機制）
• 關於 Native Application 有更多實作上的考量，請見後文。

舉例：

出自 Section 2.1，範例除外

現實中的 Client Registration

雖然規定註冊時要填寫 Client Type ，實務上好像沒什麼網站會要求填寫 Client Type 的，甚至 Client Profile，在整份 API 裡面，即使會區分 client ，也是把 client 依其 Profiles 區分。

Client Identifier （識別號）

Client 的惟一識別號，註冊時取得，對 Authorization Server 也是惟一的。

會被 Resource Owner 看到，所以絕對不可以在 Client Authentication 的時候單獨使用。

其長度 spec 並不規定。Client 不可自己猜測。Authorization Server 應該要在文件裡提及。

Section 2.2

認證 Client 的方式 (Authentication)

confidential：要有認證流程，其流程要符合 Authorization Server 的安全規範。通常是用事先核發的 credentials （如 Password 、非對稱式金鑰）。

public：可以有認證方式（不必備），但絕對不能以 Public Client 的認證方式來識別 (identify) 個別的 client 。

Client 每一次 request 只能用一種方式來認證。

Section 2.3

用 Client Password 來認證

方法 (1): HTTP Basic Auth

持有 Password 的 Client 可以用 HTTP Basic Auth 來認證（見 RFC 2617）。帳密要先用 urlencode 編過。

例如 ID 是 s6BhdRkqt3 、 Secret 是 7Fjfp0ZBr1KtDRbnfVdmIw ，則步驟如下：

Step 1: 根據 Basic Auth 的規則，把 ID 和 Secret 連起來，中間用冒號 : 分開，變成這樣：

s6BhdRkqt3:7Fjfp0ZBr1KtDRbnfVdmIw

Step 2: 用 base64 編過，變成這樣：

czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3

Step 3: 加上 Basic 前綴：

Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3

Step 4: 最後得到的 HTTP Auth 的 header 就是：

Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3

方法 (2): POST

此外還有另一種方法（不建議使用）是使用 POST 發送以下資料：

注意事項：

• 這種方法不建議使用
• 應該限制在無法使用 Basic Auth 或其他 HTTP Authentication 方式的 Client 來使用。
• 不可以把參數放在 URI 裡面。
• 要經過 TLS (https) 。
• 因為牽涉到密碼，所以要防暴力破解。

範例：（換發 Access Token 時，Client 要認證自己）

POST /token HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA
&client_id=s6BhdRkqt3&client_secret=7Fjfp0ZBr1KtDRbnfVdmIw

Section 2.3.1

其他認證方式

沒規定不能有別的，只要 Authorization Server 沒有安全上的疑慮就好了。

不過，如果要做別的認證方式，必須要建一張表記錄認證方式跟 Client ID 。

實際上的利用方式

理想與現實總是有段差距。實務上，許多大網站只支援 POST ，Basic Auth 則不一定支援。而 Facebook 則是只支援 GET （不符合「不可以放在 URI 裡面」的要求）。

未註冊的 Clients

沒規定不能有這種 Client 存在，spec 裡面也不討論。

關於 Native Application

Native Application 指的是在 Resource Owner 的設備上面安裝、執行的 Client （即桌面應用程式、手機 App），需要特別考慮安全性、平台相容性、整體的 User Experience 。

Authorzation Endpoint 會要求 Client 和 Resource Owner 的 User-Agent 之間的互動。Native Application 可以調用外部的 User-Agent 或是內嵌一個在應用程式裡面。用法如下。

外部 User-Agent：

• 用 Redirection URI 捉到來自 Authorization Server 的 response ，這個 URI 的 Scheme 要事先向 OS 註冊，才能讓 Client 成為 Scheme 的處理程式（如 facebook:）。
• 手動複製貼上 credentials 。
• 跑在本機的 Web Server。
• 安裝一個 User-Agent 的擴充套件。
• 提供一個 Redirection URI 來識別出一個放在 Server 上的、由 Client 控制的 resurce ，讓 resource 可以被 Native Application 取得（例如 Facebook 有一個固定的 Redirection URI）。

內嵌 User-Agent:

• 直接監視其狀態變化來得到 response （例如看到網址變成事先指定的，就表示得到了 redirection）
• 直接存取其 cookie。

外部或內嵌 User-Agent 的選擇

在選擇要用哪一種 User-Agent 的時候，請考慮以下這些事：

• 外部的 User-Agent 會增加達成率 (completion rate) ，因為 Resource Owner 可能已經登入到 Authorization Server 了，如此就可以免去重新登入的麻煩，從而讓使用者無縫接軌（不需要重新登入）。Resource Owner 也可能會依賴 User-Agent 特有的功能來協助登入（如自動填寫密碼、二步驗證）。
• 內嵌的 User-Agent 也許會增進使用的方便性，因為這樣就不需要切換到另一個視窗。
• 內嵌的 User-Agent 會導致安全上的挑戰，因為 Resource Owner 要在一個來歷不明的視窗裡面填入帳號密碼，如果是一般的外部 User-Egent，可以有別的視覺指引來辯認（如 URI、SSL Certificate）。內嵌的 User-Agent 會教育使用者去相信來歷不明的認證請求，進而讓釣魚攻擊更容易執行。

Grant Flow 的選擇

Native Application 可以用的流程是 Implicit Grant 和 Authorization Code Grant 。在選擇要用哪一種的時候，請考慮以下這些事：

• 使用 Authorization Code Grant 的 Native Application 最好不要兼使用 client credentials ，因為 Native App 無法保密這些資料。
• 使用 Implicit Grant 的時候，不會拿到 Refresh Token 不會，這樣子一旦過期，就需要重覆認證的流程。

Section 9

安全性問題

這裡的安全性問題出自 Section 10 ，因為跟 Client Authentcation 有關，所以直接放進來。

Client 認證的安全性問題 (Section 10.1)

Authorization Server 設立 Client credentials 是為了認證 Client。建議 Authorization Server 考慮使用比 Client password 更強的認證方式。Web Application Clients 必須確保 Client password 和其他 credentaisl 的保密。

Authorization Server 不可以為了認證 Client 而核發 Client Passwords 或是其他 credentials 給 Native Application 或是 User-Agent-Based Application Clients ，但是可以核發給特定設備上面的 Native Applciation 。

如果 Client 認證無法實施，Authorization Server 應該使用別的方式來驗證 Client 的身份。例如，要求 Client 預先設定 Redirection URI，或是讓 Resource Owner 來確認 Client 的身份。雖然，在詢問 Resource Owner 的授權的時候，即使有正確的 Redirection URI ，也不足以驗證 Client 的身份， 但是可以防止 credentails 傳遞到假的 Client 。

對於未經認證的 Clients （如 Public Clients），Authorization Server 必須考慮與其互動時會引發的安全性衝擊，且核發給這種 Clients 的其他 credentials 有外洩的可能（例如 Refresh Token），應致力降低其可能性。

偽裝成別的 Client (Section 10.2)

Client 可能會被駭，像是 credentials 外洩。這種情況發生時，惡意的 Client 可以偽裝成被駭的 Client 並取得存取 Protected Resource 的權限。

Authorization Server 必須儘可能認證 Client 。如果 Authorization Server 因為 Client 的性質而不能認證之（例如 In-Browser App 就不能認證），那麼 Authorization Server 必須要求其預先設定 Redirection URI 來接收授權的 response，並且應該利用其他手段來保護 Resource Owner 使用這種潛在的惡意 Client 。

Authorizatino Server 應該要強化明確的 Resource Owner 授權流程，並且提供 Resource Owner 關於 Client 要求的授權範圍 (scope) 以及時效。Resource Owner 在當下的 Client 的環境裡面，要不要檢閱這些資訊、要不要授權或拒絕請求，則是他的自由。

當 Authorization Server 收到重複的授權請求的時候，要是 Resource Owner 本人沒有與 Authorization Server 互動、Client 沒有認證自己、又沒有其他方法可以確定重複的請求是來自真正的 Client 而不是偽裝的，則 Authorization Server 不應該處理重複的授權請求。

Open Redirector

沒要求 Client 事先指定 Redirection URI ，可能會使得 Authorization Endpoint 變成 Open Redirector 。詳見系列文第 3 篇關於 Open Redirector 的安全性問題。

OAuth 2.0 系列文目錄

• (1) 世界觀
• (2) Client 的註冊與認證 ← You Are Here
• (3) Endpoints 的規格
• (4.1) Authorization Code Grant Flow 細節
• (4.2) Implicit Grant Flow 細節
• (4.3) Resource Owner Credentials Grant Flow 細節
• (4.4) Client Credentials Grant Flow 細節
• (5) 核發與換發 Access Token
• (6) Bearer Token 的使用方法
• (7) 安全性問題
• 各大網站 OAuth 2.0 實作差異

以下文字盡量註明 RFC 6749 原文的出處。有些原文我可能會省略，例如與 OAuth 1.0 的差異（spec 裡面有些段落有提及）、擴充 OAuth 2.0 的功能 (Extension)，這是為了讓懶人包 focus 在 OAuth 2.0 的基本使用方式。專有名詞基本上不翻譯，只適度加註中文，這是為了可以和 library 裡面常用的變數名稱保持一致。

另外，我有把 spec 原文的 txt 轉成 Markdown 來方便閱讀。

OAuth 2.0 系列文目錄

• (1) 世界觀
• (2) Client 的註冊與認證
• (3) Endpoints 的規格
• (4.1) Authorization Code Grant Flow 細節
• (4.2) Implicit Grant Flow 細節
• (4.3) Resource Owner Credentials Grant Flow 細節
• (4.4) Client Credentials Grant Flow 細節
• (5) 核發與換發 Access Token
• (6) Bearer Token 的使用方法
• (7) 安全性問題
• 各大網站 OAuth 2.0 實作差異

簡介 OAuth 2.0

在傳統的 Client-Server 架構裡， Client 要拿取受保護的資源 (Protected Resoruce) 的時候，要向 Server 出示使用者 (Resource Owner) 的帳號密碼才行。為了讓第三方應用程式也可以拿到這些 Resources ，則 Resource Owner 要把帳號密碼給這個第三方程式，這樣子就會有以下的問題及限制：

• 第三方程式必須儲存 Resource Owner 的帳號密碼，通常是明文儲存。
• Server 必須支援密碼認證，即使密碼有天生的資訊安全上的弱點。
• 第三方程式會得到幾乎完整的權限，可以存取 Protected Resources ，而 Resource Owner 沒辦法限制第三方程式可以拿取 Resource 的時效，以及可以存取的範圍 (subset)。
• Resource Owner 無法只撤回單一個第三方程式的存取權，而且必須要改密碼才能撤回。
• 任何第三方程式被破解 (compromized)，就會導致使用該密碼的所有資料被破解。

OAuth 解決這些問題的方式，是引入一個認證層 (authorization layer) ，並且把 client 跟 resource owner 的角色分開。在 OAuth 裡面，Client 會先索取存取權，來存取 Resource Owner 擁有的資源，這些資源會放在 Resource Server 上面，並且 Client 會得到一組不同於 Resource Owner 所持有的認證碼 (credentials) 。

Client 會取得一個 Access Token 來存取 Protected Resources ，而非使用 Resource Owner 的帳號密碼。Access Token 是一個字串，記載了特定的存取範圍 (scope) 、時效等等的資訊。Access Token 是從 Authorization Server 拿到的，取得之前會得到 Resource Owner 的許可。Client 用這個 Access Token 來存取 Resource Server 上面的 Protected Resources 。

實際使用的例子：使用者 (Resource Owner) 可以授權印刷服務 (Client) 去相簿網站 (Resource Server) 存取他的私人照片，而不需要把相簿網站的帳號密碼告訴印刷服務。這個使用者會直接授權透過一個相簿網站所信任的伺服器 (Authorization Server) ，核發一個專屬於該印刷服務的認證碼 (Access Token)。

OAuth 是設計來透過 HTTP 使用的。透過 HTTP 以外的通訊協定來使用 OAuth 則是超出 spec 的範圍。

Section 1

OAuth 2.0 的角色定義

• Resource Owner - 可以授權別人去存取 Protected Resource 。如果這個角色是人類的話，則就是指使用者 (end-user)。
• Resource Server - 存放 Protected Resource 的伺服器，可以根據 Access Token 來接受 Protected Resource 的請求。
• Client - 代表 Resource Owner 去存取 Protected Resource 的應用程式。 "Client" 一詞並不指任何特定的實作方式（可以在 Server 上面跑、在一般電腦上跑、或是在其他的設備）。
• Authorization Server - 在認證過 Resource Owner 並且 Resource Owner 許可之後，核發 Access Token 的伺服器。

Authorization Server 和 Resource Server 的互動方式不在本 spec 的討論範圍內。Authorization Server 跟 Resource Server 可以是同一台，也可以分開。單一台 Authorization Server 核發的 Access Token ，可以設計成能被多個 Resource Server 所接受。

Section 1.1

基本流程概觀與資料定義

以下是抽象化的流程概觀，以比較宏觀的角度來描述，不是實際程式運作的流程（圖出自 Spec 的 Figure 1）：

+--------+                               +---------------+
|        |--(A)- Authorization Request ->|   Resource    |
|        |                               |     Owner     |
|        |<-(B)-- Authorization Grant ---|               |
|        |                               +---------------+
|        |
|        |                               +---------------+
|        |--(C)-- Authorization Grant -->| Authorization |
| Client |                               |     Server    |
|        |<-(D)----- Access Token -------|               |
|        |                               +---------------+
|        |
|        |                               +---------------+
|        |--(E)----- Access Token ------>|    Resource   |
|        |                               |     Server    |
|        |<-(F)--- Protected Resource ---|               |
+--------+                               +---------------+

                Figure 1: Abstract Protocol Flow

上圖描述四個角色的互動方式：

(A): Client 向 Resource Owner 請求授權。這個授權請求可以直接向 Resource Owner 發送（如圖），或是間接由 Authorization Server 來請求。

(B) Client 得到來自 Resource Owner 的 Authorization Grant （授權許可）。這個 Grant 是用來代表 Resource Owner 的授權，其表達的方式是本 spec 裡定義的四種類別 (grant types) 的其中一種（可以擴充）。要使用何種類別，則是依 Client 請求授權的方法、 Authorization Server 支援的類別而異。

(C): Client 向 Authorization Server 請求 Access Token ，Client 要認證自己，並出示 Authorization Grant。

(D): Authorization Server 認證 Client 並驗證 Authorization Grant 。如果都合法，就核發 Access Token 。

(E): Client 向 Resource Server 請求 Protected Resource ，Client 要出示 Access Token。

(F): Resource Server 驗證 Access Token ，如果合法，就處理該請求。

Section 1.2

Authorization Grant （授權許可）

Authorization Grant 代表了 Resource Owner 授權 Client 可以去取得 Access Token 來存取 Protected Resource 。Grant 不一定是具體的資料，依 spec 裡面定義的四種內建流程，有對應不同的 grant type ，甚至在某些流程裡面會省略之，不經過 Client。

Client 從 Resource Owner 取得 Authorization Grant 的方式（前段圖中的 (A) 和 (B) 流程）會比較偏好透過 Authorization Server 當作中介。見系列文第 3 篇的流程圖。

Access Token

Access Token 用來存取 Protected Resource ，是一個具體的字串（string），其代表特定的 scope （存取範圍）、時效。概念上是由 Resoruce Owner 授予，Resource Server 和 Authorization Server 遵循之 (enforced)。

Access Token 可以加上用來取得授權資訊的 identifier （編號或識別字等），或內建可以驗證的授權資訊（如數位簽章）。也就是說，可以由 Authorization Server 間接判定這個 Access Token 的 scope 及時效，也可以嵌在 Token 裡面，但為了防止竄改，要以加密演算法來實作資料的驗證。

Spec 裡面只定義抽象層，代替傳統的帳密認證，並且 Resource Server 只需要知道此一 Access Token ，不需要知道其他的認證方式。Access Token 可以有不同的格式、使用方式（如內建加密屬性）。Access Token 的內容，以及如何用它來存取 Protected Resource ，則定義在別的文件，像是 RFC 6750 (Bearer Token Usage) 。

Section 1.4

Access Token Type

Client 要認得 Access Token Type 才能使用之，若拿到認不得的 Type ，則不可以使用之。例如 RFC 6750 定義的 Bearer Token 的用法就是這樣：

GET /resource/1 HTTP/1.1
Host: example.com
Authorization: Bearer mF_9.B5f-4.1JqM

Section 7.1

Refresh Token

用來向 Authorization Server 重新取得一個新的 Access Token 的 Token ，像是現有的 Access Token 過期而無效，或是權限不足，需要更多 scopes 才能存取別的 Resource。在概念上，Refresh Token 代表了 Resource Owner 授權 Client 重新取得新的 Access Token 而不需要再度請求 Resource Owner 的授權。Client 可以自動做這件事，例如 Access Token 過期了，自動拿新的 Token，來讓應用程式的流程更順暢。

需注意新取得的 Access Token 時效可能比以前短、或比 Resource Owner 給的權限更少。

Authorization Server 不一定要核發 Refresh Token ，但若要核發，必須在核發 Access Token 的時候一併合發。某些內建流程會禁止核發 Refresh Token。

Refresh Token 應該只遞交到 Authorization Server ，不該遞交到 Resource Server 。

Refresh Token 的流程圖：

+--------+                                           +---------------+
|        |--(A)------- Authorization Grant --------->|               |
|        |                                           |               |
|        |<-(B)----------- Access Token -------------|               |
|        |               & Refresh Token             |               |
|        |                                           |               |
|        |                            +----------+   |               |
|        |--(C)---- Access Token ---->|          |   |               |
|        |                            |          |   |               |
|        |<-(D)- Protected Resource --| Resource |   | Authorization |
| Client |                            |  Server  |   |     Server    |
|        |--(E)---- Access Token ---->|          |   |               |
|        |                            |          |   |               |
|        |<-(F)- Invalid Token Error -|          |   |               |
|        |                            +----------+   |               |
|        |                                           |               |
|        |--(G)----------- Refresh Token ----------->|               |
|        |                                           |               |
|        |<-(H)----------- Access Token -------------|               |
+--------+           & Optional Refresh Token        +---------------+

        Figure 2: Refreshing an Expired Access Token

(A) Client 向 Authorizatino Server 出示 Authorization Grant ，來申請 Access Token 。

(B) Authorization Server 認證 Client 並驗證 Authorization Grant 。如果都合法，就核發 Access Token 。

(C) Client 向 Resource Server 請求 Protected Resource ，Client 要出示 Access Token。

(D) Resource Server 驗證 Access Token ，如果合法，就處理該請求。

(E) 步驟 (C) 和 (D) 一直重覆，直到 Access Token 過期。如果 Client 自己知道 Access Token 過期，就跳到 (G)；如則，就發送另一個 Protected Request 的請求。

(F) 因為 Access Token 不合法，Resource Server 回傳 Token 不合法的錯誤。

(G) Client 向 Authorization Server 請求 Access Token ，Client 要認證自己，並出示 Refresh Token。Client 認證的必要與否，端看 Client Type 以及 Authorization Server 的政策。

(H) Authorization Server 認證 Client 、驗證 Refresh Token ，如果合法，就核發新的 Access Toke （也可以同時核發新的 Refresh Token）

步驟 (C), (D), (E), (F) 關於 Resource Server 如何處理 request 、檢查 Access Token 的機制，不在本 spec 的範圍內，跟 Token 的格式有關。RFC 6750 的 Bearer Token 有定義，見系列文第 6 篇。

Section 1.5

四種內建授權流程 (Grant Flows)

Spec 裡面定義了四種流程，分別是:

• Authorization Code Grant Type Flow
• Implicit Grant Type Flow
• Resource Owner Password Credentials Grant Type Flow
• Client Credentials Grant Type Flow

此外還可以擴充。根據流程的不同，有不同的實作細節。Client 的類型也會限制可以實作的流程，例如 Native App 就不准使用 Client Credentials ，因為這些密碼會外洩。

實務上不需要實作所有流程。我看了許多大網站的 OAuth 2 API，大部份會支援 Authorization Code Grant Flow，其他的則不一定。之後寫一篇文章整理。

這裡提一下 Clients 的類型，分成 Public 和 Confidential 兩種，根據能不能保密 Client Credentials 來區分，可以的就是 Confidential （如 Server 上的程式），不行的就是 Public （如 Native App、In-Browser App）。詳見系列文第 2 篇。

(1) Authorization Code Grant Flow

• 要向 Authorization Server 先取得 Grant Code 再取得 Access Token （兩步）。
• 適合 Confidential Clients ，如部署在 Server 上面的應用程式。
• 可以核發 Refresh Token。
• 需要 User-Agent Redirection。

(2) Implicit Grant Flow

• Authorization Server 直接向 Client 核發 Access Token （一步）。
• 適合非常特定的 Public Clients ，例如跑在 Browser 裡面的應用程式。
• Authorization Server 不必（也無法）驗證 Client 的身份。
• 禁止核發 Refresh Token。
• 需要 User-Agent Redirection。
• 有資料外洩風險。

(3) Resource Owner Password Credentials Grant Flow （使用者的帳號密碼）

• Resource Owner 的帳號密碼直接拿來當做 Grant。
• 適用於 Resource Owner 高度信賴的 Client （像是 OS 內建的）或是官方應用程式。
• 其他流程不適用時才能用。
• 可以核發 Refresh Token。
• 沒有 User-Agent Redirection。

(4) Client Credentials Grant Flow （Client 的帳號密碼）

• Client 的 ID 和 Secret 直接用來當做 Grant
• 適用於跑在 Server 上面的 Confidential Client
• 不建議核發 Refresh Token 。
• 沒有 User-Agent Redirection。

技術要求

必須全程使用 TLS (HTTPS)

因為資料在網路上面傳遞會被看見，所以 Spec 裡面規定全程必須使用 TLS ，而因為 OAuth 是基於 HTTP 的，所以就是 統統要使用 https 。實務上是定義在 Endpoints 。在某些 Client 無法實作有 TLS 的 Endpoint ，則會適度放寬限制。所以雖然這段標題寫的是「全程使用」，實際上是只有一些地方有規定需要經過 TLS ，但這個「一些」就包含了幾乎所有經過網路的地方，所以我就直接寫全程了。

至於 TLS 的版本，在 spec 寫成的時候，最新版是 TLS 1.2 ，但實務上利用最廣泛的卻是 TLS 1.0 。所以在 Spec 裡似乎沒有明確定義 TLS 的版本。

Section 1.6

User-Agent 要支援 HTTP Redirection

OAuth 2 用 HTTP 轉址 (Redirection) 用很兇， Client 或 Authorization Server 用轉址來把 Resource Owner 的 User-Agent 轉到別的地方。另外雖然 spec 裡面的範例都是 302 轉址，若要用別的方式來轉址也行，這屬於實作細節。

Section 1.7

存取 Protected Resource 的方式

關於 Client 如何利用 Access Token 存取 Protected Resource 的方式，在 OAuth 2.0 的 spec 裡面只有定義概念，具體的機制沒有定義：

• Client 要出示 Access Token 來向 Resource Server 存取 Protected Resource。
• 具體出示機制不定義，通常是用 Authorization header 搭配該 Access Token 定義的 auth scheme ，如 Bearer Token (RFC 6750) ，見系列文第 6 篇。
• Resource Server 必須驗證 Access Token 並確認其尚未過期、確認其 scope 包含所要存取的 resource 。
• 具體驗證機制不規定，通常是 Authorization Server 和 Resource Server 之間互相傳輸資料 (interaction) 以及同步化 (coordination)。

Section 7

錯誤的回應方式

Spec 裡面也不定義機制，只定義了概念以及基本的共用協定：

• 要是 Resource Request 失敗，則 Server 最好要提示錯誤 。至於 error code ，登記的方式規定在 Section 11.4。
• 任何新定義的 Authentication Scheme （如 Bearer Token）都最好要定義一個機制來提示錯誤，其 value 要使用 OAuth 2.0 spec 裡面規定的方式定義。
• 新定義的 Scheme 可能會只使用子集。
• 如果 error code 用具名參數（如 JSON 之類的 dictionary）回傳，則其參數名稱必須使用 error。
• 要是有個 Scheme 可以用在 OAuth 但不是專門設計給 OAuth ，則可以用一樣的方式來把它裡面的 error code 清單拿進來用 ※。
• 新定義的 Scheme 可以用 error_description 和 error_uri ，其意義要跟 OAuth 定義的一致。

※ MAY bind their error values to the registry in the same manner

Section 7.2

Section 11.4 裡面有規定怎麼提出新 error code 的 proposal ，有興趣的同學就看一下吧。

OAuth 2.0 系列文目錄

• (1) 世界觀 ← You Are Here
• (2) Client 的註冊與認證
• (3) Endpoints 的規格
• (4.1) Authorization Code Grant Flow 細節
• (4.2) Implicit Grant Flow 細節
• (4.3) Resource Owner Credentials Grant Flow 細節
• (4.4) Client Credentials Grant Flow 細節
• (5) 核發與換發 Access Token
• (6) Bearer Token 的使用方法
• (7) 安全性問題
• 各大網站 OAuth 2.0 實作差異

不過要先聲明：我沒有研究歷史的專業，不知道怎麼找到最正確的資料，以下除非有列出參考資料，否則都是我自己認為的，可能不正確，歡迎指正。

關於時區轉換的歷史事件

台灣的官方時區制定於 1896 ，早於中國大陸

首先，大清國直到 1911 年滅亡，都沒有實施現代意義的時區，中國大陸直到中華民國統治的 1918 才打算設置時區，根據維基百科〈中國時區〉條目的記載：

1912年之前，中國各地並沒有統一的標準時間。在王朝時代，國家的標準曆法由皇庭頒布，稱為「奉正朔」。

民國7年（1918年），中央觀象台提出將全國劃分為5個標準時區。

所以說，在 1895 年就由大清國割讓給日本的台灣與澎湖，直到 1945 由中華民國接收以前，自然沒有使用到中華民國制定的時區。那麼台灣是什麼時候開始有官方制定的時區？

答案是 1896 年的日治初年。在割讓當年的 1895 年底，日本明治天皇頒佈了敕令 167 號，從明治 29 年（1896 年）起，將大日本帝國分成兩個時區，一個叫做中央標準時，一個叫西部標準時，前者以 135°E 為基準，即現代的 UTC+9 ，後者以 120°E 為基準，即現代的 UTC+8 。大日本帝國向來使用的時區稱為中央標準時，西部標準時則是在台灣、澎湖、一部份珫球群島使用。這份敕令的內文可以在 Wikisource 的 〈標準時ニ關スル件 (公布時)〉 找到：

第一條　 帝國從來ノ標準時ハ自今之ヲ中央標準時ト稱ス

第二條　 東經百二十度ノ子午線ノ時ヲ以テ臺灣及澎湖列島竝ニ八重山及宮古列島ノ標準時ト定メ之ヲ西部標準時ト稱ス

第三條　 本令ハ明治二十九年一月一日ヨリ施行ス

這之後的故事，上過《認識台灣：歷史篇》這本課本的應該都有印象，日本人教育台灣人守時的觀念，那張「時的紀念日」海報是我印象最深的圖片。

二次大戰期間，改用與日本內地相同的 UTC+9

西部標準時一直用到二次大戰爆發，在昭和 12 年（1937 年，即日本侵華戰爭開始），日本昭和天皇頒佈了敕令 529 號，廢止西部標準時 (UTC+8)，也就是全國改用中央標準時 (UTC+9) ，包括外地（台灣、澎湖、之後佔領的香港）。

戰爭結束之後，顯然這些原本刻意與日本內地同步的時區都必須還原，在維基百科以及我隨便找的資料裡面，都只是及「國民政府接收之後，改用中原標準時間 UTC+8」，但真的是光復當天或光復之後才改時區嗎？日本投降是 8 月 15 日，到 10 月 25 日的接收儀式之間，台灣在名義上還是屬於大日本帝國，又，使用了西部標準時間的還包括琉球群島的一部份，這些地區呢？什麼時候還原的？

我在臺灣省政府公報網路查詢系統使用類似的關鍵字沒有找到切換時區的公文，只有實施夏令時間的公文。有兩種可能：①在光復之前就切換到 UTC+8 ，所以國民政府不需要有任何行政流程，或是②有切換，但不重要，所以沒記載。……怎麼可能咧。

就在我搜尋的過程中，我在國史館的網站找到一份文獻，根據推友 @FreeLeaf 的翻譯，是台灣總督府專賣局收到的內部公文，要在 9 月 21 日起改回使用西部標準時（更正啟事：先前我寫錯成「專賣局發的公文」，感謝 @FreeLeaf 再度指正）：

出處：國史館網站

又在成功大學的某個校簡史的網頁也提到：

1945（昭和20年）

8月15日：大詔宣布戰爭結束。

9月21日：本日開始，全部改為西部標準時。

這樣可以說是 9 月 21 日當天改時區嗎？但是，更關鍵的官方文件（像是台灣總督府的公文、公告等）我卻沒有找到，也不知道上哪裡找。但我比較傾向相信在 1945 年的時候，並非國民政府接收台灣之後才改時區，而是最晚 9 月 21 日就改了時區。

Update (2014/07/03) 終於找到了官方的文件，在臺灣總督府（官）報資料庫找到的檔案（需註冊）、以及其圖檔（免登入）

告示第三百八十六號

昭和十二年告示第二百七號（臺灣ノ標準時ニ關スル件）ハ之ヲ廢止シ昭和二十年九月二十一日午前一時ヲ以テ昭和二十年九月二十一日午前零時トス

昭和二十年九月十九日　臺灣總督　安藤　利吉

收錄於《臺灣總督府官報》昭和二十年九月十九日　第千十八號

簡單來說，就是廢止昭和 12 年總督府的告示第 207 號，而其為公告實施敕令 529 號，廢止西部標準時，那麼負負得正，就是回歸到西部標準時了。感謝 @rail02000 協助翻譯。

（2014/07/03 更新結束）

至於琉球群島西部是否也曾經改回 UTC+8 ，後來又再改成現在的 UTC+9 ，我很是好奇，但就沒再研究了……。

這裡稍微岔一下題。一開始提到，會研究這個是因為之前遇到一個神秘的程式 bug ，這個世界上有一個資料庫叫做 TZ Database ，這是幾乎是所有電腦作業系統都會內建一份的時區資料庫，其中當然有記載台灣的時區，比較特別的是，我今天看到的版本 2013d ，香港的時區資料，有記載香港日佔時期使用 UTC+9 時區的史實，但台灣的卻沒有。以下取自 ftp://ftp.iana.org/tz/data/asia ：

# Zone  NAME            GMTOFF  RULES   FORMAT  [UNTIL]
Zone    Asia/Hong_Kong  7:36:42 -       LMT     1904 Oct 30
                        8:00    HK      HK%sT   1941 Dec 25
                        9:00    -       JST     1945 Sep 15
                        8:00    HK      HK%sT

Zone    Asia/Taipei     8:06:00 -       LMT     1896 # or Taibei or T'ai-pei
                        8:00    Taiwan  C%sT

不過事實上，這份資料庫是公共維護的，並不是所有的資料來源都具有權威性，維護者建議，如果你知道更詳細的，可以告訴他們。在我挖到二戰期間台灣用 UTC+9 的史實之後，我寄信給維護者，不過過了一個多月，還沒有回信……。

關於台灣實施夏日節約時間 (DST) 的八卦

Update 2014/07/11 考據了所有關於日光節約時間的公文，整理在〈台灣日光節約時間之考據〉這篇新文章。

根據中央氣象局的網頁，中華民國的夏日時間制從民國 34 年到 68 年，斷斷續續實施了好幾次。但其中民國 34 年的那一次沒有在台灣實施。為什麼呢？很明顯嘛， 1945 年實施的日期是 5 月 1 日到 9 月 30 日，台灣光復是 10 月 25 日，怎麼可能實施呢？

但這個簡單的邏輯謬誤，卻被許多網頁複製貼上，稱其「台灣的日光節約時間」，卻沒有仔細考據。

在考據日光節約時間的時候，又挖到臺灣省政府的公報，其中一份公文指出，民國 36 年的夏令時間，結束日期從原本的 9 月 30 日延長到 10 月 31 日，也就是說氣象局的網頁上所說的 34 年 到 40 年間，實施日期到 9 月 30 止，在 36 年這一年要再更正。原文抄錄如下，在下圖的右下角：

臺灣省政府代電　參陸申？府人甲字第六○○二一號　中華民國卅六年九月十五日（不另行文）

事由：奉電爲本年夏令時間延長至十月三十一日午夜二十四時止等因電？？

本府所屬各機關學校：頃奉行政院卅六人字第三五一一七號代電開：「奉國府調 令，本年夏令時間定自四月十五日零時起，至九月二十日午夜二十四時止，前經 由寄通飭遵照在案。茲為勵行節約消費起見，再將是項夏令時間延長，其通用期 間至本年十月三十一日午夜二十四時爲止。等因；除分電外，仰卽遵照，幷飭爲 遵照。」等因；奉此，自應遵辦，合行電希遵照，並轉飭屬遵照。臺灣省政府 卅六申（刪）府人甲

這些 bug 我已經寄信去告知中央氣象局網站了，他們給我的回信內容是，肯定它是 bug ，會再研究，但為免誤導，先把原本的網頁下架。我現在已經看不到原本那個網頁了，但 Google 又可以找到另一個存在錯誤的網頁……。

番外篇：關於香港日佔時期實施夏日節約時間（？）的八卦

研究以上這些東西難免會去找到香港的資料，最具權威的當然應該要是香港天文台，不過香港天文台介紹夏令時間的網頁竟然是這樣寫的：

• 1941: 4 月 1 日至 9 月 30 日
• 1942: 全年
• 1943: 全年
• 1944: 全年
• 1945: 全年
• 1946: 4 月 20 日至 12 月 1 日

全年！！這不明擺著有問題的嘛！！夏季都不夏季了啊！！不可以把因為香港被日本佔領所以改時區成 UTC+9 稱做夏令時間啊！！！

哪位香港網友看到的麻煩去函指正一下吧……即使是恥辱的歷史，也要正視啊（正色）。

這個 bug 也有人在 TZ Database 裡面提到：

From Lee Yiu Chung (2009-10-24): I found there are some mistakes for the...DST rule for Hong Kong. [According] to the DST record from Hong Kong Observatory [...], there are some missing and incorrect rules. [...]

From Arthur David Olson (2009-10-28): Here are the dates given at http://www.hko.gov.hk/gts/time/Summertime.htm as of 2009-10-28:

Year Period 1941 1 Apr to 30 Sep 1942 Whole year 1943 Whole year 1944 Whole year 1945 Whole year 1946 20 Apr to 1 Dec [...]

The Japanese occupation of Hong Kong began on 1941-12-25. The Japanese surrender of Hong Kong was signed 1945-09-15.

參考資料

• 國家標準時間 - 維基百科，自由的百科全書
• Japan Standard Time - Wikipedia, the free encyclopedia
• 標準時ニ關スル件 (公布時) - Wikisource
• 明治二十八年勅令第百六十七號標準時ニ關スル件中改正ノ件 - Wikisource
• 台灣總督府專賣局的公文（國史館）
• 世紀回眸（成功大學網站）
• 臺灣省政府公報 民國 36 年秋
• 臺灣省政府公報網路查詢系統
• 臺灣ノ標準時ニ關スル件 （需登入）、其圖檔（免登入）
• 臺灣總督府府官報資料庫（需登入）
• 中央氣象局的網頁 已下架

延伸閱讀

• 程式設計界的前輩良葛格所寫的時間與日期基本知識【Joda-Time 與 JSR310 】（2）時間的 ABC by caterpillar | CodeData

TZInfo::AmbiguousTime: 1895-12-31 23:59:59 UTC is an ambiguous local time.

出現的機率很低，大概數個月才一次， User Agent 都是搜尋引擎的 bot ，所以也不能算是惡意 request 。這個 exception 不會影響網站的運作，但就是很好奇為什麼會出現。

前些日子終於找到時間來深入研究了，結果是 TZInfo 這個時區 gem 的問題。

Ambiguous Time: 程式無法正確轉換當地時間到 UTC

根據文件， TZInfo 裡面的 AmbiguousTime exception ，只會從 Timezone.period_for_local 和 Timezone.local_to_utc 裡面 raise 出來，表示「這個本地時間在 UTC 可能有多個對應的時間，所以不知道怎麼轉成 UTC」。示例：

> time = Time.new(1895,12,31,23,59,59)
 => 1895-12-31 23:59:59 +0800

> TZInfo::Timezone.get("Asia/Taipei").local_to_utc(time)
 => TZInfo::AmbiguousTime: Time: 1895-12-31 23:59:59 UTC is an ambiguous local time.

> TZInfo::Timezone.get("Asia/Shanghai").local_to_utc(time)
 => 1895-12-31 15:54:02 UTC

上述示例使用的 TZInfo 版本是 0.3.37 。

如果升級到 TZInfo 1.0.1 就沒有這個問題，但是， TZInfo 1.0 系列的時區資料，是直接讀 OS 內建的 IANA TZ Database ，而不是像以前的版本，是將 IANA TZ Database parse 出來變成 Ruby representation ，包成 gem ，載入 tzinfo 的時候將資料結構塞到記憶體裡面。示例：

> time = Time.new(1895,12,31,23,59,59)
 => 1895-12-31 23:59:59 +0800

> TZInfo::Timezone.get("Asia/Taipei").local_to_utc(time)
 => 1895-12-31 15:59:59 UTC

> TZInfo::Timezone.get("Asia/Shanghai").local_to_utc(time)
 => 1895-12-31 15:54:02 UTC

原本在 0.3.x 使用的資料庫，抽出成 tzinfo-data ，在 TZInfo 1.0.x ，如果 gemset 裡面有安裝了 tzinfo-data ， TZInfo 就會改用 tzinfo-data 並讀取 Ruby representation ，這樣的話，就會發生同樣的錯誤。

要排除這個問題，最簡單的做法當然就是升級 TZInfo 到 1.x 系列，因為顯然這個問題只有在 0.3.x 才有。不過 Rails 綁 tzinfo ~> 0.3.37 （3.2 系列綁在 ActiveRecord ， 4.0 系列綁在 ActiveSupport），所以寫 App 的人也沒辦法直接 override 。最後我們決定 wontfix。

更正啟事：根據 TZInfo gem 維護者的說法，會 raise AmbiguousTime 才是正確的行為，因為根據 TZ Database 的規則，把這樣的時區轉換視為「在 UTC 時間到 1895 年 12 月 31 日 15:54:00 的時候，在 Asia/Taipei 時區的時鐘，要往回撥 6 分鐘」，因此，從當地時間轉到 UTC 就有兩種選擇，所以才會是 AmbiguousTime 。至於為什麼採用 OS 內建的資料庫就沒事，請見下文。

他提出的 Workaround 是，既然程式不知道要選哪一個時間，就幫他選一個吧，例如，第一個：

	> TZInfo::Timezone.get("Asia/Taipei").local_to_utc(time) {|periods| periods.first }
	=> 1895-12-31 15:53:59 UTC

整整 6 分鐘的 AmbiguousTime

嘗試窮舉哪些時間會有問題：

require 'tzinfo'

tpe = TZInfo::Timezone.get("Asia/Taipei")

time = Time.new(1895,12,31,0,0,0)

while time.year < 1896
  begin
    tpe.local_to_utc time
  rescue TZInfo::AmbiguousTime => e
    puts "Conversion failed: #{time}"
  ensure
    time += 1
  end
end

這結果是從 23:54:00 到 23:59:59 每一秒都有問題：

Conversion failed: 1895-12-31 23:54:00 +0800
# ...
Conversion failed: 1895-12-31 23:59:59 +0800

但只有整整 6 分鐘。

去翻了 IANA TZ Database ，發現到有定義 Local Mean Time 是 GMT+8:00:06 ，並且這個定義直到 1896 年才廢止，改用時區 UTC+8 ，符合史實：日本統治台灣之後，在 1896 年訂台灣和一部份珫球群島採西部標準時，以現在的說法就是 UTC+8 。見 http://en.wikipedia.org/wiki/Time_in_Japan 。

# Zone  NAME        GMTOFF  RULES   FORMAT  [UNTIL]
Zone    Asia/Taipei 8:06:00 -       LMT     1896 # or Taibei or T'ai-pei
                    8:00    Taiwan  C%sT

所謂「整整 6 分鐘都無法轉換」可能跟這個 LMT 的定義有關。

目前只能猜想是 TZInfo library 的問題，可能是 0.3.x 的轉換程式沒有考慮到某些極端狀況。若你的程式很在意這個「從無到有」的過渡時期，請考慮改用 TZInfo 1.0.x 。

更正啟事： 根據 TZInfo gem 維護者的說法，Ambiguous Time 是預期的行為，至於為什麼使用 OS 內建的 TZ Database 和使用 tzdata-info 的結果不同，可能是 OS 內建的版本不支援 64-bit timestamp。問完之後會再整理成一篇，圍觀網址： https://github.com/tzinfo/tzinfo-data/issues/1 。

後來稍微考據了一下台灣的時區過渡過程，發現了一些有趣的事，下一篇文章詳述。

以上全都是用 CSS 做出來的，不是一個一個反白再選字體（要是這樣我也不用寫一篇了）。

要做到這一點，必須使用 CSS3 @font-face 提供的 unicode-range descriptor 。這招也不是沒有人玩過，在 2011 年底，就有人拿來設定西文裡面 "&" (ampersand) 的字體了，而在中文圈裡，@ethantw 在 2011 年中期開始製作漢字標準格式・標點樣式，來修正不同漢字地區的標點符號，當前的版本也應用了 unicode-range。

以下就來解釋如何完成的。

CSS3 @font-face 的 unicode-range

根據 W3C 的 spec ，unicode-range 是這樣用的：

@font-face {
  font-family: MyCustomFont;
  unicode-range: U+00-7F; /* ASCII */
  src: local(Helvetica), local(Arial); /* 先找 Helvetica ，沒有的話用 Arial */
}

這樣子的話，在 CSS 裡面就可以使用 font-family: MyCustomFont ，但是它只會套用在 U+00 到 U+7F 這些字元（Basic Latin，即 ASCII），即使 Helvetica 和 Arial 有提供其他字元，例如帶有重音符號的拉丁字母 é （U+00E9，在 Latin-1 Supplement block），它還是不會套用這個字體。

unicode-range 的寫法

unicode-range 的 syntax 有以下 3 種（範例由 W3C spec 而來）：

• U+416 - 單一個 code point
• U+400-4FF - 某個 code point 區間（含頭尾）
• U+4?? - 尾碼任意的 code point，以這個例子來說，等義於 U+400-4FF。

如果要指定多個 ranges ，就是用逗號 , 分開：

@font-face {
  /* ... */
  unicode-range: U+123, U+456-7FF, U+9??;
}

unicode-range 預設值是 U+0-10FFFF ，也就是涵蓋了所有 Unicode 的 code point space，白話的意思就是「不寫的話，這個 font face 要套用到所有字元」。

對同一個 font-family 的特定 unicode-range 設字體

這招在 W3C 的 spec 有教，以下的例子是「拉丁字、注音符號、日文假名用特別的字體，其他用預設的 Heiti TC（如果沒有 Heiti TC，就使用微軟正黑體）」。我們都知道，Heiti TC 的拉丁字、注音符號、日文假名都很醜，至於微軟正黑體是為了在 Windows 7 上面 Demo 用的：

@font-face {
  font-family: MyCustomFont;
  src: local(Heiti TC), local("微軟正黑體");
  /* no unicode-range; default to all characters */
}

/* Latin characters 專用 */
@font-face {
  font-family: MyCustomFont; /* 同樣的 font-family */
  unicode-range: U+00-024F;  /* Latin, Latin1 Sup., Ext-A, Ext-B */
  src: local(Helvetica),     /* OS X preferred */
       local(Arial);         /* Other OS */
}

/* 注音符號專用 */
@font-face {
  font-family: MyCustomFont;      /* 同樣的 font-family */
  unicode-range: U+3100-312F;     /* Bopomofo */
  src: local(LiHei Pro),          /* OS X */
       local("微軟正黑體"); /* Windows Vista+ */
}

/* 日文假名專用 */
@font-face {
  font-family: MyCustomFont;            /* 同樣的 font-family */
  unicode-range: U+3040-30FF;           /* Hiragana, Katakana */
  src: local(Hiragino Kaku Gothic Pro), /* OS X */
       local(Meiryo);                   /* Windows Vista+ */
}

body {
  font-family: MyCustomFont, sans-serif;
}

最後的結果，就是拉丁字、注音符號、日文假名用了另一種字體，而其他的文字則是用 Heiti TC；在 Windows 上面，則是使用微軟正黑體（假設使用者沒有自行安裝 Mac OS X 的字體）。

覆寫 Generic Family

Generic Family 就是 sans-serif 、 serif 這些基本的 style 。我在嘗試 @font-face 的時候，很好奇能不能把 font-family 指定成 Generic Family ，用來覆寫瀏覽器預設（或在偏好設定裡指定）的這些字體。實際試了一下，還真的可以，只要把上面的 CSS 裡面的 MyCustomFont 改成 sans-serif ，然後把 body 的 font-family 設成 sans-serif ，效果就跟之前一樣。

最終效果

文章一開頭的效果跟上面所示的例子其實不太一樣：

1. 沒有預設字體，交給瀏覽器決定。

• 漢字用 Heiti TC
• 其他一樣

並且把 serif 也加進來。實際 demo 在此。

後記：Web Font

會做這個實驗，是前幾天看到 @ethantw 做的漢字標準格式・標點樣式，可以讓標點符號符合台、港式（置中）或中、日式（左下角）的標點。我很是好奇他怎麼能夠只針對標點符號去設定字體，於是打開了他的 CSS ，發現他在 @font-face 裡面使用了 unicode-range。

我以前只知道 @font-face 拿來玩 Web Font，也就是說即使你的電腦裡沒有這個字體，也可以讓瀏覽器去下載並套用。現在才知道 @font-face 裡面可以寫 unicode-range 並且重覆寫 font-family: MyCustomFont 來製作出混合了數種字體的新字體。

事實上，上一次 Chrome 18 字體亂象發生時，我曾經嘗試在 User Agent Stylesheet （Custom.css）裡面覆寫 sans-serif 的字體為 Helvetica ，想說這樣應該可以讓 Chrome 的字體 fallback 機制回到 OS X 處理。但那時候這樣做卻沒有成功，所以轉而去搞 Extension 。日前 Safari 6 也出現了同樣的功能，於是試了一下 custom stylesheet ，還真的可以 hack 掉 fallback 機制，那時候再回去 Chrome 試這招 override sans-serif 的 hack，竟然就可以了。

不過說到 Web Font 這技術，因為設計給漢字文化圈的字體都比較大（以 MB 為單位，因為字元多），所以這項技術只流行在歐美的網站（用拉丁字母，數十 KB 而已）。當然台灣也有救世字在嘗試提供中文 Web Font 服務，最近的 HITCON 2012 也展示了這項服務的潛力。

參考資料

• Character range: the unicode-range descriptor - CSS Fonts Module Level 3 - W3C
• Unicode block - Wikipedia
• 24 ways: Creating Custom Font Stacks with Unicode-Range

Copy as Markdown 是我做的 Chrome Extension ，專門做這些事：

1. 把目前的分頁標題及網址複製成 Markdown
2. 按右鍵把超連結複製成 Markdown
   • 如果你是在圖片上按右鍵，則複製出來的會是連結包圖片 [![](img url)](link url)
3. 按右鍵把圖片複製成 Markdown
4. 把目前視窗的所有分頁及網址複製成 Markdown 的列表（！）

一按就完成，手指可以空出來做更多事，我是說寫稿。

載點

Chrome 網路商城由此去 、原始碼由此去 (MIT)。

截圖

大概像這樣（其實下圖的 markdown code 我也是直接用這個 extension 複製的… 超懶人 XD）：

Known Issues

已知問題有幾個：

1. 在 Windows 的 Chorme，複製連結的時候，不會複製連結文字。這個原因是 Mac OS X 會自動在按右鍵的時候就選取文字，但 Windows 版本不會。這是我上架之後才發現的 bug ，沒用 Windows 測試真的不行 orz
2. 複製圖片的時候，抓不到 alt 屬性；這個我還在找答案，很顯然直接從 Chrome 的 Context Menu OnClickData 物件 是抓不到的。這個問題要是解決了， 1 或許也就解決了。

以下心得文

這是我最近這兩天開始做的，但其實已經想很久了。壓倒我的最後一根稻草，是最近在學 Code Academy 的 JavaScript 課程，總覺得終於有條理地學了 JavaScript ，那就把以前因為沒技術所以寫不出來的東西寫一寫吧。

第一次做 Chrome Extension ，當然第一個是參考官方文件。不過官方文件似乎只列出了基本的 API ，使用範例也很少，就老是叫你翻 Sample 。

別的不說，光是複製到剪貼簿，就是上 StackOverflow 找到答案的（非常怪的招數），這個功能我以為會是 Chrome API 要提供的… Orz

功能大致寫完了以後，要上架時又碰到阻礙。

首先是 Chrome Web Store 要求上架時要有 1280x800 或 640x400 解析度的螢幕截圖。

1. 我想說 Chrome Web Store 的圖片這麼小，我隨便切個小圖就行了。
2. 第一次放，不滿 640x400 ，叫我再傳一次。
3. 第二次放，我切 643x404 ，上傳後跟我說「尺寸不符」，所以是一定要完全一致才行…
4. 第三次放，我切得剛好 640x400 ，上傳後卻跟我說「請上傳 1280x800 的解析度」
5. 第四次放，就只好先用別的工具把 Chrome 縮到 1280x800 ，抓圖，然後用 Preview.app 小心切…
6. 而且上架之後才發現他還是縮到 640x400 了，那你叫人家放大圖放身體健康的？

此外還要放一張宣傳圖，是 440x280 ，為了這個只好再切一次。不過這好像是要放在 Web Store 的 index ，哪天這個 app 被擠到上面就需要了（會有這一天嗎？）。

最後要付 US$5.00 的一次性註冊費，這麼便宜當然不介意了。不過我竟然看到這個畫面：

五樓你評評理啊！當然我在姓名之間加入一個空格就通過了 Orz

不過這次還真的學到了怎麼做 Chrome Extension ，以前還想說要學怎麼做 Firefox Extension ，但最近兩年已經沒在用 Firefox 了...。

2006 年我基於嘗鮮的心態去買了一張 TaiwanMoney ，那時候覺得台北有悠遊卡很酷。所以我的 blog 有一些 TaiwanMoney 的文章。

以我以前居住的台南市區而言，公車族使用 TaiwanMoney 的還是少之又少，學生通勤族大多數都是買紙印的月票，我就用過興南客運和高雄客運的。至於大學生和上班族，大部份也都騎機車，在台南會像我這樣搭公車四處跑的人真的是異類。高中職學生大部份都會在 18 歲的時候去考駕照當成年禮，我自己也在 20 歲考到駕照後，幾乎沒上過公車，假期回台南都是騎機車。即使是在大眾運輸最發達的（舊）高雄市，在高雄捷運通車後，TaiwanMoney 因為通訊協定跟一卡通不同，出入都得走公務門，也讓 TaiwanMoney 的發展更加受阻。

現在這一刻終於還是來了，TaiwanMoney 在 6/9 終止業務，交易到 8/31 為止，現金贖回也是。我就去贖回了，然而這其中有很波折的故事。

我收到這則訊息是 6 月中，是在 PTT 看到的。原本計畫七月中旬回台南做兵役專科體檢的時候一併去玉山銀行辦贖回，不過櫃員跟我說要等幾個工作天才能拿到現金（具體數字忘了），因為要跟台北總行做什麼會計手續；或是轉帳到我在其他銀行的帳戶，扣手續費。我那時候不知道腦子在想什麼，就問說既然要跟台北總行確認，那我能不能去台北辦贖回？他說可以，我也就走了。事實上我現在想想，更不懂為什麼我那時候不跑去興南客運在台南火車站附近的營運處處理就好了。

總之我還是把這張卡帶到了台北，去住所附近的玉山銀行處理。一進門，服務人員以為我是要剪信用卡（看起來很像），但我說不是，總之他帶我到某個櫃台前面。我想台北的櫃員應該也不知道，一坐下來就把來龍去脈說了一遍，櫃員一開始也不知道是什麼卡，問了襄理，還打了電話求救，過程中還問了身份證字號（不過這卡是不記名的）。

大概過了 10 分鐘，就說因為該行沒有讀卡機，所以要我留卡，寄到有讀卡機的其他分行處理，並且問了我要匯到哪個帳戶。我說這卡是買斷的，我要回來領卡，櫃員打電話問了遙遠的同事，確定可以。我要求寫一張字據什麼的證明我有留卡，之後回來拿卡也方便，也就印了卡片的正反面。這張字據一式二份，我留一份。

不到三個工作天，就收到了玉山銀行的電話，說已經匯款了，刷簿子發現沒有扣手續費（科科）。隔天又打電話來說可以去原本那間分行拿卡，今天就去拿了。

這張卡片我留作紀念，它見證了非接觸式交通票證在南部地區的實驗，以後要在南部推這種服務的單位，應該要參考他們為什麼失敗的經驗。我也不想在這裡說太多事後諸葛的話，留待其他對大眾運輸比較在行的人來評論吧。

以下的操作全是在 Mac OS X 10.6.8 完成的。

What is launchd ?

launchd 管理的 background process 有四種：

1. Launch Daemon: 在開機時載入 (load) 。
2. Launch Agent: 在使用者登入時載入。
3. XPC Service: 好像是 10.7 才有的，我還沒灌 10.7 ，先跳過。
4. Login Items: 在 User 登入時執行。有兩種方法可以用程式新增項目到 Login Item：
1. Shared File List：會出現在 Account 偏好設定的 Login Item 清單。
2. Service Management Framework：這個就不會出現在 Login Item 清單。

Launch Daemon & Launch Agent

如果你打開 Activity Monitor ，並切換到 Hierarchy view ，你會發現有個 launchd 會在最上層，跟它同層的只有 kernel_task ，它下面有很多 child processes 的 user 都是 root ，其中還有一個 launchd ，啟動的 user 是你自己，它底下的 child processes 的 user 也幾乎都是你自己。當這些 processes 是由 launchd 載入 launchd property list file 來執行的時候，前者由 root 執行的稱為 Launch Daemons ，後者由使用者執行的稱為 Launch Agents 。

launchd property list file 就是你會在 LaunchDaemon 或 LaunchAgents 目錄中看到的 *.plist 檔案（以下統稱 plist 檔，反正本文講到的 plist 檔也只有這種用途）。它是 XML 格式，不過咱們別這麼糾結手刻 XML ，你直接按兩下打開就是 Property List Editor ，滑鼠點一點就好，不糾結。

launchd Service Process Lifecycle

開機時，會先載入 OS Kernel ，載入完成後就執行 launchd ，用來載入 system-wide services （daemons）。這個 system-wide launchd 在開機時會做這些事：

1. 載入 (load) 存放在這些目錄下的 plist ：
• /System/Library/LaunchDaemons
• /Library/LaunchDaemons
2. 註冊那些 plist 裡面設定的 sockets (port) 和 file descriptors
3. 執行 (run) KeepAlive = true 的 daemons ，當然 RunAtLoad = true 的也會啟動。

在使用者登入以後，會執行屬於該使用者的 launchd ，負責處理 Launch Agent ，做的事跟上面載入 Launch Daemon 很像，差別在於它從以下的目錄載入 plist：

• /System/Library/LaunchAgents
• /Library/LaunchAgents
• ~/Library/LaunchAgents

在使用者登出、關機或重新開機時，會觸發 Termination event。接受登出、關機、重新開機使用者指令的 process 是 loginwindow 。它會先向使用者確認，一但確認，就會對每個由該使用者的 launchd 所啟動的 processes 送出 termination signal，如果是 Cocoa 則送出 Cocoa API 的 event，其他的就送出 SIGTERM 要他們自我了斷，45 秒之後，除了 Cocoa 的應用程式可以丟出某個 error 來取消這整個 termination process，其他還沒結束的都會被 kill 掉。

這就是為什麼 loginwindow 這個 process 會一直存在，它要負責把該使用者執行起來的 processes 統統清掉。而 per-user services 都關掉以後，就回到 loginwindow ，或是執行關機、重新開機的流程，後兩者就是照著差不多的流程去關掉所有 system-wide services 。

launchd-compatible Daemon Programming Guide

Listen to SIGTERM

On-Demand Daemon

當該 service 需要被使用時，而相對應的 program 沒有跑成 process 時，會自動把該 service 給跑起來。例如某個 TCP/IP service 聽某個 port，當這個 port 有封包進來時， launchd 會把相對應的 service 給啟動，這種行為叫做 on-demand 。

當然，也有 non-on-demand daemon （好繞舌），其實也就是 keep-alive daemon ，這也是傳統意義上的 daemon ，我是說那種一直躲在牆角默默執行，直到有人找他，他才跳出來回一下話，回完了以後又繼續躲在牆角的那種。只要把 KeepAlive 這個 key 設成 true ，它就會在 plist 被 launchd 載入 (load) 時執行 (run) 起來。要是那個 process 死掉，launchd 會知道，馬上再把它開起來。所以如果你試著去 Activity Monitor 砍掉這種 daemon ，它就馬上會復活。

No fork or exec

當一個 process 跑起來 10 秒內就死掉， launchd 會判定為 crash ，然後試著重新執行。要是你用傳統的 fork-exec style ，就可能會造成無限迴圈。

No setuid / setgid / chroot / chdir etc.

No pipe redirection hell for fd 0, 1 or 2

其他應用

工作排程

搭配 LaunchOnlyOnce 的話可以模擬 at ，但對我來說，如果要用 launchd 只臨時做一件事，還不如直接 at 方便。

監視檔案或目錄異動

也可以用來清 queue ，只要 directory 裡面有東西，就會執行 job 直到空為止，可以用來做 mail server 或 notification 。設定在 QueueDirectories 這個 key 。

See also:

• man 5 launchd.plist
• man 1 launchctl ，也就是管理 Launch Daemons / Agents 的工具
• Technical Note TN2083: Daemons and Agents

大家都知道 Git 有個特色就是 branch 開很大開不用錢，但很多 branches 各自開發，總要在適當時機 merge 進去 master 。看過很多 git 操作指南都告訴我們，可以妥善利用 rebase 來整理看似很亂或是中途可能不小心手滑 commit 錯的 commits ，甚至可以讓 merge 產生的線看起來比較簡單，不會有跨好幾十個 commits 的線。

rebase 的意義：重新定義參考基準

首先要提一下 rebase 的意思，我擅自的直譯是「重新 (re-) 定義某個 branch 的參考基準 (base)」。把這個意思先記起來，比較容易理解 rebase 的運作原理。就好比移花接木那樣（稼接），把某個樹枝接到別的樹枝。

在 git 中，每一個 commit 都可以長出 branch ，而 branch 的 base 就是它生長出來的 commit ，rebase 也就是把該 branch 所長出來的 commit 給改去另一個 commit 。不過，因為 rebase 會調整 commit 的先後關係，弄不好的話可能會把你正在操作的 branch 給搞爛，所以在做 rebase 之前，最好開一個 backup branch ，什麼時候出差錯的話，reset 回 backup 就行了。

以下用實際的例子來操作比較容易解釋。看 log 的程式是 GitX (L) 。

Update 2012/06/28：也可以看 ihower 的錄影示範 ，實際操作會比讀文字來得容易懂。

例如我要寫個網頁，列出課堂上的學生。我把樣式的設計 (style) 跟主幹 (master) 分開，檔案有 index.html 和 style.css 。

到目前為止有以下的 commit history：

style 完成了一小部份，而接下來要修飾的頁面是 master 裡面有改過的，如何讓 style 可以繼承 master 呢？就是用 rebase 把 style branch 給接到 master 後面了，因為 rebase 是「重新定義基準點」。就像是在稼接時，把新枝的根給「接」在末梢上。

rebase 的基本指令是 git rebase <new base-commit> ，意思是說，把目前 checkout 出來的 branch 分支處改到新的 commit。而 commit 可以使用 branch 去指（被指中的 commit 就是該 branch 的 HEAD），所以現在要把 style 這個 branch 接到 master 的 HEAD （dc39a81e），就是在 style 這個 branch 執行

git rebase master

完成之後，圖變這樣：

果然順利接起來了。

而在執行的過程中會看到：

First, rewinding head to replay your work on top of it...
Applying: set body's font to helvetica
Applying: adjust page width and alignment

這是它的操作方式，照字面上的意思，就是它會嘗試把當前 branch 的 HEAD 給指到你指定的 commit （在這裡是原本 master 的 HEAD，也就是 dc39a81e），然後把每個原本在 style 上面的 commits （d242d00c..0b373e34） 給重新 commit 進去 style 這個 branch (re-apply commits)。也由於是「重新 commit」，所以 rebase 以後的 commit ID (SHA) 都不一樣。

那如果過程中有 conflict 呢？後文會提到。

fast-forwarding: 可以的話，直接改指標，不重新 commit

接著再開個新的 branch 叫 list ，專門改學生清單，同時另一個人也在改 style 這個 branch ，修飾網頁的整體裝飾。改啊改，變成這樣分叉的兩條線：

]

list 改到一個段落，沒有問題了，就想 merge 進 master 。在 master branch 做

git merge list

這時 git 發現，剛好 master 直接指到 list 的 HEAD commit 也行 ，所以 git 直接就改了 master 的 commit ID ，也就是所謂的 fast-forward，熟悉 C 語言的同學應該對這種指標移動不陌生。完成之後就是這樣：

]

rebase --onto: 指定要從哪裡開始接枝

list 繼續改，style 還是繼續改，變這樣：

]

現在 style 要開始裝飾學生清單了，而學生清單是 list 這個 branch 在改的。於是 style 應該要 rebase 到 list ，可是這時管 list 的說，我後面幾個 commits 還沒敲定，你先拿 64a00b7e (add their ages) 這個 commit 當基準，這我改好了。所以這時候，應該要把 style 這個 branch 接到 64a00b7e 的後面。

該怎麼辦呢？這時就要用 git rebase --onto 了。指令是

git rebase --onto <new base-commit> <current base-commit>

意思是說，把當前 checkout 出來的 branch 從 <current base-commit> 移到 <new base-commit> 上面 ，就像是在稼接時，把新枝的根給「種」在某個點上，而不是接在末梢。（這似乎也是稼接最常用的方式？有請懂園藝同學的指教一下）

再看一下 commit history：

]

現在 style 是 based on dc39a81e (add some students)，要改成 based on 64a00b7e (add their ages)，也就是

• <current base-commit> = dc39a81e
• <new base-commit> = 64a00b7e

那就來試試看

git rebase --onto 64a00b7e dc39a81e

]

果然達到了目的，style 現在是 based on 64a00b7e 了（當然 commit IDs 也都不同了）。

conflict 的處理

接著改 style 的人修改了學生清單的樣式，可是他很機車，他要改 index.html 裡面的東西（實際情況是，list 裡寫了一個 table，但寫 css 總要有些 class 或 id 的 attributes 才能設定）。剛好改 list 的人也在他自己的 branch 裡面改，這時候，在 rebase 試著 re-apply commits 的過程中，必定會產生 conflict。

]

現在 list 要利用到 style 裡面修飾好的樣式，在這個情況下，就是把 list 給 rebase 到 style 上面，也就是在 list branch 做 git rebase style 。不過你會看到這個：

First, rewinding head to replay your work on top of it...
Applying: add gender column
Using index info to reconstruct a base tree...
Falling back to patching base and 3-way merge...
Auto-merging index.html
CONFLICT (content): Merge conflict in index.html
Failed to merge in the changes.
Patch failed at 0001 add gender column

When you have resolved this problem run "git rebase --continue".
If you would prefer to skip this patch, instead run "git rebase --skip".
To restore the original branch and stop rebasing run "git rebase --abort".

跟預期的一樣出現了 conflict。當然，它會先試著自動 merge ，但如果改到的行有衝突，那就得要手動 merge 了，打開他說有衝突的檔案，改成正確的內容，接著使用 git add <file> （要把該檔案加進去 staging area，處理 rebase 的程式才能 commit），再 git rebase --continue 。

完成以後就會像這樣：

]

Interactive Mode: 偷天換日，自定重新 commit 的詳細步驟

接著 style 和 list 又陸續改了一些東西，主要是 list 裡面加了表單元件，而 style 則繼續修飾網頁整體設計。到了一個段落，該輪到 style 修飾 list 的表單了。目前的 commit history 長這樣：

]

不過在 style 要 rebase 到 list 上面之前，管 list 的人想把 list 上面的一些 commits 給整理過，因為他發現有這些問題：

• "wrap the form with div" 太後面了，想移到前面
• "fix typo of age field name" 跟 "add student id and age..." 可以合併
• "add student id and age ..." 裡面東西太多，該拆成兩個
• "form to add more *studetns*" 這 message 有錯字 "studetns"
• "add gender select box" 裡面的程式碼有打錯字（囧

上面提到了 rebase 運作的方式是重新 commit 過一遍，那這個「重新 commit」的過程，能不能讓程式設計師來干預，達到偷天換日修改 commit 的目的呢？當然可以，只要利用 rebase 的 Interactive Mode。Git 的靈活就在這裡，連 commit 的內容都可以改。

如何啟動 interactive mode 呢？只要加入 -i 的參數就行了。以這個例子來說，list branch 是 based on 0580eab8 (fill in gender column) ，要從這個 commit 後面重新 apply 一次 commits ，也就是：

git rebase -i 0580eab8

接著會以你的預設編輯器打開一個檔案叫做 .git/rebase-merge/git-rebase-todo ，裡面已經有一些 git 幫你預設好的內容了，其實就是原本 commits 的清單，你可以修改它，告訴 git 你想怎麼改：

# git rebase -i
pick 2c97b26 form to add more studetns
pick fd19f8e add student id and age field into the form
pick 02849bf fix typo of age field name
pick bd73d4d wrap the form with div
pick 74d8a3d add gender select box

# Rebase 0580eab..74d8a3d onto 0580eab
# ...[chunked]

第一個欄位就是操作指令，指令的解釋在該檔案下方有：

• pick = 要這條 commit ，什麼都不改
• reword = 要這條 commit ，但要改 commit message
• edit = 要這條 commit，但要改 commit 的內容
• squash = 要這條 commit，但要跟前面那條合併，並保留這條的 messages
• fixup = squash + 只使用前面那條 commit 的 message ，捨棄這條 message
• exec = 執行一條指令（但我沒用過）

此外還可以調整 commits 的順序，直接剪剪貼貼，改行的順序就行了。

調整 commit 順序、修改 commit message

首先我想要把 "wrap the form with div" 移到 "form to add more studetns" 後面，然後 "form to add more studetns" 要改 commit message （有 typo），那就改成這樣：

# git rebase -i
reword 2c97b26 form to add more studetns
pick bd73d4d wrap the form with div
pick fd19f8e add student id and age field into the form
pick 02849bf fix typo of age field name
pick 74d8a3d add gender select box

接著儲存檔案後把檔案關掉（如 vim 的 :wq），就開始執行 rebase 啦，遇到 reword  時會再跳出編輯器，讓你重新輸入 commit message 。這時我把 studetns 改正為 students ，然後就跟平常 commit 一樣，存檔並關掉檔案。

# git commit
form to add more students

# Please enter the commit message for your changes. Lines starting
# ...[chunked]

完成後會看到：

Successfully rebased and updated refs/heads/list.

再看 commit history ，的確達到了目的，而且 list 這個 branch 一樣還是 based on 0580eab8 ，後面那些剛剛 rebase 過的 commits 統統換了 commit ID ：

]

合併 commits

剩下這些要做：

• "fix typo of age field name" 跟 "add student id and age..." 可以合併
• "add student id and age ..." 裡面東西太多，該拆成兩個
• "add gender select box" 裡面的程式碼有打錯字

現在來試試看合併，一樣是 git rebase -i 0580eab8 ，並使用 fixup 來把 commit 給合併到上一個（如果用 squash 的話，會讓你修改 commit message ，修改時會把多個要連續合併的 commit messages 放在同一個編輯器裡）：

# git rebase -i
pick c3cff8a form to add more students
pick 7e128b4 wrap the form with div
pick 0d450ea add student id and age field into the form
fixup 8f5899e fix typo of age field name
pick e323dbc add gender select bo

完成後再看 commit history ，的確合併了：

]

修改、拆散 commit 內

剩下了拆 commit 和訂正 commit 內容。現在先來做訂正 commit ，這個學會了就知道怎麼拆 commit 了。

在這裡下 edit 指令來編輯 commit 內容：

# git rebase -i
pick c3cff8a form to add more students
pick 7e128b4 wrap the form with div
pick 53616de add student id and age field into the form
edit c5b9ad8 add gender select box

存檔並關閉之後，現在的狀態是停在剛 commit 完 "add gender select box" 的時候，所以現在可以偷改你要改的東西，存檔以後把改的檔案用 git add 加進 staging area ，再打

git rebase --continue

來繼續，這時候因為 staging area 裡面有東西，git 會將它們與 "add gender select box" 透過 commit --amend 一起重新 commit 。

最後是拆 commit 。怎麼拆呢？剛剛做了 edit ，不是停在該 commit 之後嗎？這時候就可以偷偷 reset 到 HEAD^ （即目前 HEAD 的前一個），等於是退回到 HEAD 指到的 commit 的前一個，於是該 commit 的 changes 就被倒出來了，變成 changed but not staged for commit ，再根據你的需求，把 changes 給一個一個 commit 就行了。

實際的操作如下。首先是用 edit 指令來編輯 commit 內容：

# git rebase -i
pick c3cff8a form to add more students
pick 7e128b4 wrap the form with div
edit 53616de add student id and age field into the form
pick 4dbcf49 add gender select box

接著使用

git reset HEAD^

來把目前的 HEAD 指標給指到 HEAD 的前一個，指完之後，原本 HEAD commit 的內容就被倒出來，並且也不存在 stage area 裡面， git 會提示有哪些檔案現在處於 changed but not staged for commit：

Unstaged changes after reset:
M	index.html

現在我可以一個一個 commit 了，原本是 add student id and age field ，我想拆成一次加 student id field ，一次加 age field 。commit 完成以後，再打

git rebase --continue

這次因為 staging area 裡面沒東西，所以就繼續 re-apply 剩下的 commits 。

現在打開 log 看，拆成兩個啦！

]

掌管 list branch 的人折騰完了，便告訴管 style 的說，可以 rebase 了，git 再度拯救了苦難程序員的一天。

]

更多 rebase ：

• Git 版本控制系統(3) 還沒 push 前可以做的事 by ihower
• 寫給大家的 Git 教學 by littlebtc

猶記得我國小三年級時（1997），第一次有電腦課，因為我們好歹是台南市的國小，所以也有個看起來有點像樣的電腦教室：大顆 CRT 螢幕、 Windows 95、Office （版本忘了）。那時候電腦課教的，不外乎是奇摩搜尋、畫賀卡、小畫家、錄音機等，我人生第一個電子郵件也是在這時候辦的（但早就沒在用了），還有一些林林總總的。不過有個東西我特別記得：MIDI。

Windows 95 、 98 都有內建一些 MIDI 檔，既然是國小的電腦課嘛，就會教大家怎麼播這些 MIDI 、去網路上找 MIDI 檔，最有名的就是「MIDI 音樂廳」，而且剛剛才發現，經過十來年的一直換網址，它竟然還活著，只是最新歌曲似乎都是十幾年前的事了。

當時我對於電腦可以播音樂，非常驚訝，每次電腦課我都花很多時間去搜集 MIDI，多半是當時流行的卡通、日劇主題曲，然後存到軟碟片帶回家。有些網站不給載，當時不懂網頁技術的我，只知道去 IE 暫存資料夾撈 .mid 檔出來，可以說是我成為宅宅的濫觴。（說到這裡，現在小朋友還知道甚麼是軟碟片嗎？）

後來到了國小六年級，第一次擁有 MP3 隨身聽（32MB），才第一次知道 MIDI 是不能放進 MP3 隨身聽的。結果呢？身為宅宅的我竟然不知道去哪裡找到「把 MIDI 變成 MP3」的工具，於是乎，一首首 MIDI 就被音源器重新演譯、進了我的 MP3 隨身聽。

只是有一天，我在重灌電腦的時候，忘了在事前把 My Documents 給解除鎖定，重灌後的 Windows 解不開舊的資料夾（註），於是就只好忍痛與上百首 MIDI 檔案說再見了，其中有不少我很愛的音樂，每天都要聽的那種。因此還哭了好幾天。

上了國中，就開始流行 MP3 了，這時候的我也不再拘泥於只有電子音源的 MIDI，但也就跟 MIDI 漸行漸遠了。直到現在。

為甚麼現在突然想起來呢？是因為昨天我在 Mac App Store 下載了 MIDITrail（Open Source，也有 Windows 版），它可以把 MIDI 各軌的譜讀出來，並視覺化彩現在 3D 空間中，Camera 可以任意轉，播放到該音符時還會出現圈圈，如下圖：

然後就開始拿出我殘存（多數是那次慘案後憑印象重新下載的）的 MIDI 檔出來邊聽邊看，頗是新鮮，我控 MIDI 這麼久，第一次知道可以把 MIDI 視覺化（雖然似乎早就有人做出這這種應用了），也許是因為太久沒聽了吧，這兩天睡覺前都在把玩它、又去網路上找一些 MIDI 回來聽，所以前面才有突然發現 MIDI 音樂廳還活著的事實。

二十一世紀已經過了十分之一，即使因為科技進步，電子影音都逐漸走向高解析度（高畫質、高音質），不過有時候，純電子的音樂還是可以讓我有一些莫名其妙的感動呢。

不過根據我的習慣，應該也是兩三天就玩膩，把它從 Dock 移除了吧，趁現在心情還在，把它寫下來。

註：當時我以為解不開，不過昨天有一位 Windows 大師告訴我，其實只要拿回擁有者就行了（囧）

幾乎每個文化都有髒話存在，通常嚴重具攻擊性的髒話都與性交有關。可是就我從小到現在的觀察發現，大部份人對於西洋電影的髒話接受度甚高，不覺得那有什麼「髒」的，有的人甚至以美式英文的髒話代替國語或台語的髒話，即使它們的本義相同（例如，使用「F●●k」或「法克」而不使用「幹」）。

雖然從文化的觀點來看，因為我們不是美國人，所以對於那些充滿嚴重攻擊意義的字眼，沒有什麼感覺，也是很正常的。

但我不能認同的是，某些人視國台語髒話為禁忌，卻完全不忌諱英語的髒話：

• 台灣的電影裡出現大量髒話→下流電影
• 美國的電影裡出現大量髒話→ ^_^ so what?

說得明白一點，不管是在社會什麼階層的人，生活中多少一定會接觸到髒話，或髒話的字眼（而不具有攻擊的意義）。像電影這種會忠實呈現文化的藝術作品，為什麼要視髒話為禁忌？好像電影裡有髒話就一定是下流電影之類的，更何況髒話也不是全部都代表攻擊，君不見美國電影中，年輕一代在覺得高興的時候也會隨口說出一兩個髒話，對的，就像一些台灣年輕人用「幹」表示開心的語助詞，一樣的道理；那美國人會覺得這種電影下流或兒童不宜嗎？台灣人呢？

──雖然我也覺得電影『艋舺』裡面出現的髒話是太多了，不過我認為，那是因為我沒有過那樣的經歷，所以才覺得他們滿口髒話不甚習慣；甚至，這部電影如果少了髒話的元素，會讓人覺得很假。

如果你覺得，在罵人的時候，英語的髒話跟國台語的髒話一樣髒（即：你認為都是非常嚴重攻擊），那我不是在說你。

講這麼多就是，我覺得電影裡如果出現 F●●k 應該要翻作「幹」才合理啊！不管它是不是用在攻擊或侮辱，都很合適啊不是嗎 XDD。當然也可能是因為代理商認為這個字在原文裡就具有很強的攻擊意義，找個比較和緩的詞來代替，會比較好一點，看看英美出品的一些影視節目，還會把髒話直接做消音，有的還把嘴形打馬賽克，就知道他們對於那些字的反感有多強烈。但反效果就像我上面講的，有些人會以為那些美國髒話不具有那麼強的攻擊性。

最後呢，你可以不同意我認為髒話應該要合理出現的論調。在日常生活中，我也不太喜歡用髒話的字詞（是啦我是有比較常講啦，不過講一次就後悔一次，而且只跟熟的、可以接受的人講），同時我也有不少朋友對於完全不具攻擊意義的髒話字眼感到很不舒服的人，這種話當然生活中還是少說點好。

我在批評的是那些認為台灣髒話不好，而美國髒話好的人啊！講美國髒話並沒有比較高級啊！

隨文附上維基百科關於髒話的條目網址，不喜勿入…。

不過，維基百科裡面記載的髒話，好像定義比較寬鬆，連某些攻擊性極低（普遍接受）的也列入了。

p.s. 本文把某些美國髒話標以馬賽克，是為了不要讓笨笨的美國製搜尋引擎以為這篇文章充滿髒話。至於中文的部份，我想那些電腦到現在還分不清楚幹是樹幹還是勞動。

程式碼都在 GitHub 的 Repository，不會用 git 的話可以按 Download 下載 zip 或 tgz 包裝。

兩年了，再回頭看自己大一寫的程式碼，除了有很濃厚的 MapleBBS-itoc 的影子之外，就是又雜又難看啊而且還很少註解的 code 了。檔案的結構也是亂七八糟的，濫用 external function reference -_-，連 Makefile 都是抄 MapleBBS-itoc 的 XDD

「視窗」是用 curses 函式庫寫出來的，在 Unix-like 的 OS 都有內建了。而 Windows 只要用 Dev-C++ 和 PDCurses (有 Dev-C++ 的 Package) 也可以編譯並執行喔（而且是 Static Linking，執行檔不用函式庫就能玩了；為什麼是 Static Linking...最近才在上系統程式，還沒學到怎麼改那個 Linking Scheme，囧rz）

至於編譯的方法和所需要的函式庫都描述在 GitHub Repo 的 Readme 了，自個兒去看吧。

License... 我不知道要用哪個 = = 事隔多年也不知道有沒有抄到別人的 code 了，不敢亂寫授權。GNU/GPL、BSD 還是別的？五樓你說呢？

p.s. 其實我從來沒玩贏過一次電腦的黑白棋，不管是×電族裡面的，還是 Windows XP 的...。

p.s. 2 不要怪我沒說，這支程式裡有很多 bug，而且 Makefile 當年是亂抄亂寫的，一點規範都沒有，請不要拿來當範例程式！（可以拿來當「寫得很爛的程式」的 case study 啦）

「高雄」原名「打狗」這個我是已經知道了。不過「打貓」竟然是「民雄」的古名，這我就很訝異了。印象中只知道打貓約在嘉義地區，但沒有很確定在哪裡（事實上是根本沒上網查過）。

所以當然是丟進 Google 找找看。

「打狗」是平埔族語，原意是「竹林」。日本人依其音似日文「高雄」二字的訓讀(*1)（たかお）而改名。

「打貓」是平埔族一個社（部落）的社名。日本人依其音似日文「民雄」二字的訓讀（たみお）而改名。

有趣的地方是，原本漢人寫出來的是「打」字輩，到了日文竟很巧地變成了「雄」字輩。

這些原本都屬於平埔族原住民的語言，先是被空耳(*2)聽成閩南語的音，轉寫成漢字，之後又被空耳聽成日文音，自 1920 年以來我們便接受了這樣的寫法，即使 1949 年國民政府來台，即使 21 世紀初正名運動如此火熱，我們還是接受了它。──當然別忘了，在這之前還有荷蘭人。

雖然，在台灣歷史上，有許許多多的地名都有著這樣的命運。我們知道大員也是一個平埔社名，漢人不斷改變它的漢字寫法，它後來甚至還延伸為整個台灣島的稱呼。我想，這是當時的大員社歷代頭目們想不到的吧。

參考資料：

1. PTT 實業坊 Railway 板 〈[情報] 1920年驛名改正〉 一文，作者 weichia。文章代碼 #1AcVOYPb
2. 高雄歷史 - 維基百科，自由的百科全書
3. 打狗港 - 維基百科，自由的百科全書
4. 民雄鄉 - 維基百科，自由的百科全書
5. 台灣舊地名列表 - 維基百科，自由的百科全書
6. 大員 - 維基百科，自由的百科全書

*1 訓讀是指以自己的母語來朗讀漢字，例如我們看到「小泉純一郎」會讀「ㄒㄧㄠˇ ㄑㄩㄢˊ ㄔㄨㄣˊ ㄧ ㄌㄤˊ」而不是「こいずみじゅんいちろう」。相對的概念是音讀，也就是以接近原文的音來讀漢字，就像日本人習慣把中文姓名讀作古漢音，即為音讀。

*2 空耳是日文詞，意思是故意把別的語言的音聽成自己語言的音。

今天剛好講到一個很有趣的段落： (p. 115)

國語（漢語官話的北京話方言）身為台灣地區現行的標準語 (通用全國，從政府官員到國民教育的語言)，是如何產生的？

文中提到標準語大抵上有四種形成的方式：

一是以境內多數語言為標準語。諸如中國、法國。

二是以外來少數語族的語言(外來語)為標準語。這通常發生在殖民地，強勢民族統治弱勢民族而產生的。但殖民地脫離殖民統治後，可能會（意識形態地）採用原先的語言，或沿用原殖民國的語言。諸如亞非多數原屬西洋人殖民地的國家。

三是把境內所有主要語言都提升到官方語言的地位，如比利時、端士、香港。

四是以少數語言為標準語，因為多數語言太多了大家吵翻天乾脆一不做二不休改用少數語。

讀完了這一頁，老師便提問了：

「那麼台灣屬於哪一種呢？」

我們知道現在的國語身為標準語，其地位確立是基於（一）多數語。（這應該沒人反對；我想國語教育在台灣還算是成功的吧？）

那麼，國民政府「播遷來台」初期推行國語，應該歸在哪一類呢？

有人很直覺的就說了「外來語。」這讓我很驚訝其實。

我心裏突然有了一個想法，於是說了如下：

當初國民政府來台的時候，是把台灣當作反攻大陸的復興基地，君不見那地圖上還是美妙的秋海棠。其政府制度直接承襲中華民國那一套（或說整套搬過來用），當然也包括民國 20 幾年(?)的時候確立的「以國語為中華民國標準語」的制度。

因此，當時的政府認為台灣是中華民國的一部份，自然而然就要使用這樣的制度。

結論是，它是多數語──僅管它「多數」的分母在國民政府的眼中，和在當時台灣民眾的眼中，可能有所不同。

（一些年代的細節不是當時說的，是現在寫文章補的）

而持「外來語」觀點的同學則提到：

國民政府視台灣為一個反攻大陸的基地，同時也僅止於此。其行徑近乎殖民統治，情況類似第二點的外來語。因此國語的官方地位的確立，可以算是外來語。 其實他這麼說好像也不無道理。

後來的討論頗熱烈的，有支持多數語論者，有支持外來語論者，還有人把日治時期的漢文和口頭漢語（閩南話、客家話）搞混了。

基本上「國府初期的台灣人使用閩南語居多，相對而言國語是少數語」這點沒有人否認，但它是否會影響這個問題的答案呢？

最後有某個同學提出一個觀點，這是不是一種「意識形態」？

「從不同的觀點來看，就會有不同的結果。」

老師最後沒有給答案，她只說了：

這個問題沒有標準答案。沒錯，你從不同的角度看，就會有不同的答案。如果現在換到以原住民為本的角度，你就會發現，原住民一直都是處於被殖民狀態，一直要被迫學習其他完全不同語系的語言，每換一個統治民族就要換一次。對他們而言，國語也只是另一種外來語罷了。

而從國民政府的角度來看，台灣只不過是中華民國的一小部份，中華民國規定國語，台灣當然也用國語。在國民政府的眼裡，國語是屬於多數語。

如果再從當時本來就住在這塊土地上的漢人來說，可能閩南語才是多數語，而使用國語的人成為少數族群，國語變成一種外來語。 「意識形態沒那麼可怕的，」她說，「只是觀點不同罷了。」

如此討論後，我也認為這個問題沒有一個標準的答案。

解釋方式不同，得到的自然就不同。

黃宣範教授的書中還有許多有趣的事，諸如當初國民政府如何實現「中華民國國語推行模範省」的目標的具體方式，以及日本人對待同一件事（語言造成的族群意識）的操作手段。

歷史也是可以如此有趣的。

──那為什麼我以前讀得要死要活  = =