LSAT(Lightning Service Authentication Token)

https://scrapbox.io/files/63a0422eccd5c1001e718dac.png

はじめに

このドキュメントでは、LSATと呼ばれるプロトコル標準を規定することを目的としています。LSATとは、Lightning Service Authentication Tokenの略です。LSATは、Lightning Labsが開発した、認証と有料APIのための新しい標準プロトコルです。LSATは、認証としての役割と、有料APIの決済メカニズム（チケットと捉えることもできる）の両方を果たすことができる。LSATを活用することで、サービスやビジネスは、無料とサブスクリプションの間に位置する、新しい階層の有料APIを提供することができます。

LSATは、高級な認証トークンまたはクッキーと見なすことができます。通常のクッキーと異なるのは、暗号的に検証可能なベアラー クレデンシャルである点です。LSATトークンは、エンドサービスプロバイダによってのみ作成可能なマカロン内に、すべての機能をエンコードします。LSATの仕様は、HTTPとライトニングネットワークを組み合わせて、ライトニングネットワーク上に構築された次世代の有料APIのためのシームレスなエンドツーエンドの支払い＋認証フローを作成するために使用されています。

上記のシステムは空想ではなく、LSATは今日、Lightning Labsによって、Lightning Networkの非保護的なオン/オフランプであるLightning Loopの認証+支払いソリューションとして使用されています。また、Lightning Labsは、LSATを意識したリバースプロキシであるapertureをオープンソース化し、我々の全てのシステムで使用しています。このセクションでは、LSATの動機、系譜、ワークフローを簡単に説明します。より詳細な仕様については、この仕様書の後のセクションをご覧ください。

忘れ去られたHTTPエラーコード

現在、私たちが知っているHTTPは、開発者がサービスプロバイダーが作成したAPIを簡単に利用できるようにするために、いくつかのエラーコードを使用しています。例えば、よく知られている 200 OK というエラーコードは、HTTP レスポンスが成功したことを示します。401 Unauthorizedは、クライアントが認証を必要とするページやリソースにアクセスしようとしたときに送信されるなど。このほかにも多くのエラーコードが存在し、より一般的に使用されているものもある。その中で、あまり利用されていないエラーコードに「402 Payment Required」があります。その名の通り、このコードはクライアントがまだ料金を支払っていないリソースにアクセスしようとしたときに返されます。HTTP仕様のほとんどのバージョンで、このコードは "reserved for future use" としてマークされています。多くの人が、これはある種のデジタルキャッシュやマイクロペイメントスキームで使われることを意図していると推測していますが、最初の HTTP 仕様が起草された時点ではまだ存在していませんでした。

しかし、それから数十年後、私たちは広く使われているデジタル・キャッシュ・システムを手に入れました。ビットコインです。さらに、マイクロペイメントに特化した新しいネットワーク、ライトニングネットワークも誕生しました。Lightning Labsの設立当初、私たちはLightning Networkが可能にする有料の従量制APIの可能性に惹かれました。私たちはLN自体で決済部分を解決しましたが、次の課題は、既存のAPIに簡単かつ拡張可能な方法で落とし込めるプロトコルを作ることでした。これに対する我々のソリューションがLSATプロトコルです。

LightningネイティブなWebにおける認証とAPIペイメント

Lightning は、ウェブ上のサービスやリソースにアクセスするためのデファクトの支払い方法として機能する可能性を秘めています。この新しいウェブでは、ユーザーが見えないピクセルでウェブ上を追跡され、広告を配信されたり、ユーザーが自分の電子メールを提供し、スパムや追跡の対象となるのではなく、ユーザーがサービスに対して支払い、その過程で将来の認証やアクセスに使用できるチケット/レシートを取得できるとしたらどうでしょう。

この新しいウェブでは、電子メールアドレスやパスワードは過去のものとなっています。その代わり、サービスやリソースにアクセスするために、暗号化されたベアラ・クレデンシャルが購入され、ユーザーによって提示されます。この新しいWebでは、クレジットカードは、もはや作成されているすべての素晴らしい経験へのゲートキーパーとして機能しません。LSATは、よりグローバルで、よりプライベートで、より開発者に優しい新しいウェブの創造を可能にします。

この時点で、好奇心旺盛なユーザーは疑問に思うかもしれない。このような仕組みはどのように機能するのだろうか？このような仕組みは、どのように機能するのだろうか、支払いと受領のステップは原子的なのだろうか。なぜ、ユーザーはこれらの「チケット」の1つを偽造することができないのでしょうか？

HTTP + マカロン + ライトニング = LSAT

LSATとは、Lightningで取得した特定のサービスやリソースに対するチケットのことです。チケット自体には、どのリソースにアクセスできるかが暗号化されています。このチケットはコピーしたり、友達に渡したりして、同じリソースにアクセスできるようにすることができます。また、チケットを減衰させることで、そのリソースの少し弱いバージョン（例として、480pのビデオストリーミングが可能）を友人に提供することもできます。一方、サービス側では、特定のユーザーのために特別なチケットを作成し、ローテーション、アップグレード、さらにはチケットの失効を行うことができます。

このチケットは、実はマカロンなのです。マカロンは、API認証情報のための柔軟な標準であり、すでにlndがそのデフォルト認証メカニズムとして使用している。LSATプロトコルは、ユーザーがライトニングネットワーク上でこれらのチケットの1つをアトミックに購入することを可能にします。ユーザーがLightning請求書とともに支払いを必要とするリソース（402 Payment Required）にアクセスしようとすると、HTTP（またはHTTP/2）上で部分的なLSATが提供されます。この部分的なLSATは、請求書に支払いを行い、支払いのプリ画像を取得することで完全なLSATに変換できます（請求書は支払いハッシュに支払われます：payment_hash = sha256（pre_image））。

エンドクライアント、ライトニングウォレット、モバイルアプリケーション、ブラウザ（および拡張機能）で適切に統合すれば、上記のフローは、ユーザーが今日慣れているクレジットカードのフローよりもさらにシームレスになる可能性があります。また、サーバーは誰がチケットの代金を支払ったかを知る必要がなく、支払いが成功したことだけを知ることができるため、よりプライベートな環境にも対応できます。

アプリケーションとユースケースの例

LSAT規格は、多くの新しいユースケース、価格モデル、およびアプリケーションを構築することができ、これらはすべて主要なマネーレールとしてライトニングネットワークを使用しています。この規格はHTTP/2上で定義されているため、既存のgRPCサービスへのゲートアクセスもサポートするよう自然に拡張することができます。これは、認証と支払いのロジックをアプリケーションのロジックから強く切り離すことができるため、非常に強力です。現在、ライトニングループでは、このLSATを利用して、ユーザーに軽量な認証機構を提供しています。

LSATはライトニングネットワークの決済機能を利用しているため、従量制APIを簡単に作成することも可能です。従量制APIとは、ユーザーが事前にサブスクリプションにコミットする必要がなく、対象のリソースやサービスに対してその都度支払いを行うことができるAPIです。開発者はLSATを使って、計算機やディスクスペースなどのリソースを継続的にユーザーに請求するアプリケーションを作ることができる。ユーザーが支払いをやめた場合、そのリソースは停止、回収され、別の有料ユーザー用に再割り当てされます。もう一度言いますが、この規格は双方向ストリーミング API をサポートする gRPC をサポートしているので、課金式のストリーミング ビデオやオーディオ サービスも作成することができます。

さらに、LSATはAPIアーキテクチャ・レベルでのイノベーションも可能にします。その一例が、自動化されたティアアップグレードだ。多くのAPIは通常、いくつかの階層を提供し、ユーザが階層を上がるにつれて、より多くの、あるいは追加のリソースにアクセスできるようにします。通常、ユーザーはウェブページを手動で操作して、より高い階層へのアップグレードや低い階層へのダウングレードを要求する必要があります。ユーザーは新しいエンドポイントにアクセスし、以前の階層と比較して追加された機能または増加したリソースへのアクセスをコード化したアップグレード版 LSAT を取得します。また、LSATを利用してA/Bテストを行うこともできます。ユーザーのサブセットに異なるLSATを提供し、サービスに送信すると、ターゲットリソースやサービスがわずかに異なるバージョンで表示されます。

このセクションでは、LSAT標準の起源、動機、ワークフロー、可能性、使用例について概要を説明しました。この後のセクションでは、LSATプロトコルの仕様について、より深く掘り下げていきます。

認証の流れ

この章では、ユーザとクライアントソフトウェアの視点から、高レベルの認証フローを説明します。

ユーザーの視点からの要件は単純です。ユーザは、できるだけ摩擦なくサービスを利用できることを望んでいます。サービスを利用するためには、まずAPIアクセスキーを取得する必要があるという概念には慣れているかもしれませんが、そのために個人情報を使ってアカウントを登録することは必ずしも望んでいないのです。

LSATプロトコルを利用したサービスは、まさにこの要件を満たしています。アカウントを作成することなくAPIキーを利用することができます。また、情報を入力する必要がないため、APIキーの取得はユーザーにとって透過的に、バックグラウンドで行うことができる。

LSATに対応したクライアントソフトは、このプロトコルを利用したサーバーに接続すると、数十万円程度の請求書を受け取ることができる。クライアントソフトウェアがその請求書を支払うと（ユーザー定義の閾値を超えない場合は自動的に行われる）、有効なAPIキーまたは認証トークンを構築することができます。このトークンは、クライアントのソフトウェアによって保存され、今後のすべてのリクエストに使用されることになる。

詳細な認証フロー

以下のステップでは、さらに下の図について説明します。これは、認証サーバによって保護されたリソースにアクセスしたいクライアントソフトウェアのために行われる呼び出しの流れです。

例として、Lightning Labのループサーバとループアウトスワップを行いたいloopdクライアントについて見ていきます。

初めてループアウトを行う

1. loopユーザがloopサーバとスワップを行いたい。次のコマンドを入力します。loop out <amount>と入力してリターンキーを押します。

2. loopdクライアントプログラムは、loopサーバーにスワップを開始するために連絡する。

3. クライアントからの呼び出しは、常に認証サーバーを経由する必要があります。リバースプロキシは、この例ではApertureである。認証プロキシは、クライアントがLSATを送信していないことに気づき、ループサーバーへのアクセスを許可することができません。ループサーバーにアクセスすることができません。

4. apertureは、自身のlndインスタンスに、新しいトークンの取得に必要な少額のインボイスを作成するよう指示する。新しいトークンを取得するために必要な少額の請求書を作成するよう、自分のlndインスタンスに指示する。

5. apertureは、インボイスに加えて、新しいアクセストークンも作成します。インボイスに加えて、アパーチャーは、インボイスに関連する新しいアクセストークンを作成します。このトークンは、暗号化されておりトークンは、インボイスの支払いが完了した時点で初めて有効となるように暗号化されています。

6. トークンと請求書は、未使用のHTTPヘッダー402 Payment Requiredでクライアントに返送されます。未使用のHTTPヘッダー402 Payment Requiredとしてクライアントに返送される。

7. Loopdは、この返されたエラーコードを理解し、そこから請求書を抽出します。loopdはこのエラーコードを理解し、そこから請求書を抽出し、接続されているlndインスタンスに自動的に支払いを指示する。請求書の支払いを指示する。

8. 請求書の支払いにより、loopdクライアントは支払いの暗号証明（プリ画像）を所有することになる。請求書の支払いにより、loopdクライアントは支払いの暗号化証明（プリイメージ）を所有することになる。この証明は、クライアントのローカルストレージに保存されます。この証明は、アクセストークンとともにクライアントのローカルストレージに保存されます。

9. アクセストークンとプリ画像の組み合わせにより、完全に有効なLSATが生成されます。暗号的に検証されたLSATが生成されます。

10. クライアントはループサーバに元のリクエストを繰り返し、今度はLSATをリクエストに添付する。今度はLSATをリクエストに添付する。

11. 認証サーバーはリクエストを傍受し、LSATを抽出し、検証する。認証サーバーはリクエストを傍受し、LSATを抽出し、それを検証する。LSATは有効であるため、リクエストは実際のループサーバーに転送される。ループサーバーに転送され、スワップが開始される。

12. スワップサーバーの回答がクライアントに返され、スワップが開始される。スワップが開始される。

13. プロセス全体は、ユーザーに対して完全に透過的である。ユーザが気づくのは最初のループで数秒の遅延が発生することです。各ループは同じトークンを使用し、全く遅延はありません。

https://scrapbox.io/files/639709dc6f3025001edf0483.png

それ以上のループはすべて

1. サーバーへの新しいリクエストごとに、クライアントはローカルに保存されているトークンを自動的に添付するようになりました。トークンを添付する。

2. トークンが有効期限内であれば、上記のステップ9〜13が実行される。トークンの有効期限が切れた場合、サーバーは手順4からやり直し、クライアントに新しいトークンの取得を指示する。新しいトークンを取得するようクライアントに指示する。

マカロンの造形と検証

概要

本章では、Lightning Service Authentication Token (LSAT) のマカロンコンポーネントの仕様について概説します。LSATは、トークンに許可された機能を指定するマカロンと、トークンの支払い証明となるプリイメージで構成されています。マカロンは、改ざん防止、簡単なローテーション、属性、さらにLSAT対応サービスを統合するアプリケーションが追加機能を委譲するための減衰が可能であり、LSATに最適な素材と言えます。本章では、LSATの一部としてマカロンがどのように作成され、減衰され、検証されるかを説明します。この章では、macaroonの仕組みと、認証にどのように役立つかを理解することが必要です。マカロンの入門的な研究論文をざっと読んでおくと、役に立つかもしれません。

マカロンの造幣局

マカロンには、ルートキーに対応する公開識別子、注意事項のリスト（減衰を実現する方法）、署名の3つの基本的な構成要素があります。新しいマカロンの鋳造には、公開識別子とそれに対応するルートキーが必要なだけです。

各マカロンには、マカロンの偽造を防ぐために、公開してはならない独自の暗号化されたランダムなルートキーが必要です。各ルート鍵は32バイトで構成され、エントロピーとサイズのトレードオフを実現している。ルートキーはマカロンの検証に不可欠であるため、安全かつ確実に保管されなければならない。

マカロンの識別子

秘密鍵に対応するのは、マカロンの公開識別子のSHA-256ハッシュであり、マカロン自身の静的情報を含んでいる。初期構築時、公開識別子には以下のものをリスト順に含める必要がある。

注：ここで指定するデータは、特に断りのない限りすべてビッグエンディアンでエンコードされている。

バージョン - バージョンによって、マカロンの設計を反復することができる。2バイトの符号なし整数でエンコードされなければならない。

支払いハッシュ - 支払いハッシュは、請求書の支払い要求をマカロンにリンクする。支払い要求が満たされると、支払い者は支払いの証明として対応するプリ画像を受け取ります。この証明は、マカロンと一緒に提供され、請求書が履行されたかどうかを確認することなく、LSATの支払いが行われたことを確認することができます。

ユーザー識別子 - 一意のユーザー識別子により、サービスは、サービスレベルメータリングの文脈で有用な異なるマカロンにまたがってユーザーを追跡することができます。マカロンの識別子の代わりに32ランダムバイトのユーザー識別子が使用されますが、これは後者がサービスレベルのアップグレードの場合などに取り消される可能性があるためです。

警告による減衰

警告は、マカロンの権限と、マカロンがうまく利用できる文脈を制限する述語である。マカロンを検証する際には、各カベイトの述語が評価され、真となる必要がある。その柔軟性から、適切に評価するためには、サービスに対するリクエストの中にある追加のコンテキストが必要になる場合があります。

バージョン 0 のマカロンの警告は、キーと値のペアを文字列としてエンコードしたもので、キーと値の間は 1 文字の = で区切られます。キーは洞窟を一意に識別し、それがどのように評価されるべきかについてのコンテキストを提供し、値は評価自体のコンテキストを提供します。注意書きをどのように形成するかについて更なる制限はありませんが、Lightning Labs サービスでは、主に以下の 3 種類の注意書きが適用されます。

対象サービス

マカロンがアクセスを許可される対象サービスは、カベで表現されます。注意書きのキーは services であり、その値はカンマで区切られたターゲットサービスのリストである。各ターゲットサービスは、サービス名とその階層からなる2タプルで構成される。階層はサービスごとに異なり、基本階層となる0から始めなければならない。特定のサービス層がその能力や制約を更新した場合、同じ層のマカロンが、今は古い能力や制約で使用されていることを検出する方法が必要である。サービス層にコミットすることで、このようなケースを検出し、古くなったマカロンを失効させ、新しい能力や制約を持つ新しいマカロンを鋳造して、（それが有効であると仮定して）シームレスにアップグレードすることが可能です。

このケイバットを検証する際、マカロンがコミットしていないサービスにアクセスしようとした場合、無効とみなす必要があります。複数のサービスに関するカベが存在する場合、検証では、カベが発生するたびに、前のものより多くのアクセスを制限していることを確認する必要があります。

サービスの能力

各サービスは、サービスが提供する能力によってさらに制限することができ、これらはまた別の注意事項として表現されます。これらの注意書きは、サービス名の前に_capabilitiesで終わるキーを持ち、値は許可されたサービス機能のカンマ区切りリストで構成されています。このタイプの注意書きは、特定のマカロンに、サービスの機能のサブセットへのアクセスのみを許可します。

特定のサービスに対するケイパビリティに関する注意事項が存在しない場合、マカロンはそのサービスのあらゆるケイパビリティにアクセスすることができます。同じサービスに複数のケイパビリティ・ケイパビリティが存在する場合、検証では、ケイパビリティ・ケイパビリティの出現ごとに、前のものより多くのアクセスを制限していることを確認する必要があります。

サービスの制約事項

各サービスは、与えられた階層に対して独自の制約注意事項を定義して、マカロンの能力をさらに制限することができます。各制約は、キーに適用されるサービス能力の接頭辞が付き、キーの残りの部分には、制約を評価する方法に関するサービスのコンテキストが含まれる、注意書きの形式を取ります。警告の値は、制約評価のためのパラメータを指定します。

マカロン内で同じ制約の複数の警告が見つかった場合、検証では、制約の各出現が前よりもアクセスを制限していることを確認する必要があります。

例として、ベースティアーのLightning Loopマカロンで、Loop Outの月間ボリュームが2BTC、Loop Inのボリュームが無制限のアクセスは、次のようになります。

code:code

identifier:

version = 0

user_id = fed74b3ef24820f440601eff5bfb42bef4d615c4948cec8aca3cb15bd23f1013

payment_hash = 163102a9c88fa4ec9ac9937b6f070bc3e27249a81ad7a05f398ac5d7d16f7bea

caveats:

services = lightning_loop:0

lightning_loop_capabilities = loop_out,loop_in

loop_out_monthly_volume_sats = 200000000

マカロンホルダーは、マカロンを第三者と共有する場合、より限定的な権限で共有できるよう、柔軟に設計することができます。上記の例では、マカロンホルダーは、以下の注意事項を追加することで、マカロンの機能を制限し、月間1BTCの量のLoop Inのみにアクセスを許可する（Loop Outは許可しない）ことができます。

code:code

lightning_loop_capabilities = loop_in

loop_in_monthly_volume_sats = 100000000

マカロンの検証

マカロンの検証は3つのステップからなり、マカロンの採掘者と、マカロンが対象とするサービスである認証者の2者が関与します。マカロンの作成者は、マカロンが有効であることを確認するために署名チェックを行い、認証者は、マカロンがサービスにアクセスするために必要な権限を有していることを確認します。

最初のステップでは、マカロンが鋳造者によって鋳造されたものであり、改ざんされていないことを確認する。これはマカロンのHMACチェインを計算することで行われる。マカロンのルートキーと識別子から始まり、マカロンの最終署名に到達するまでに、その洞穴を通してさらに減衰するものを含む。これらが一致しない場合、そのmacaroonは無効である。また、マカロンに対応する有効なルート鍵がない場合も、無効とみなされる。

第2段階は、マカロンが有効な支払い証明書（プリ画像）を提供したことを確認するもので、マイニング担当者が同様に行う。マカロンは請求書の支払いハッシュをコミットするので、これは些細なステップである。

最後のステップでは、マカロンがサービスへのアクセスを許可されていることを確認する。これは、マカロンのサービス固有の警告述語が、アクセスされるサービスに対して真であることを保証することで行われる。もし、1つでも正しくなければ、そのマカロンは無効である。未知の警告がある場合、マカロン保持者が他のアプリケーションのためにマカロンをさらに減衰させることができるため、認可者はその評価をスキップしなければならない。

マカロンの取り消し

マカロンに基づく認証サービスを悪用されないようにするために、マカロンの取り消しができるようにする必要があります。これは、採掘者がマカロンに対応するルート鍵を削除することで実現できる。こうすることで、採掘者は無効にされたマカロンの署名を検証することができなくなり、対象となるサービスにマカロンが到達することがない。

取り消しは、マカロンのサービス階層をアップグレードする際にも有効です。アップグレード前のマカロンが無効にされ、アップグレード後のマカロンだけが使用できるようになります。