shinten-ship 0.2.0 → 0.2.2

package/README.ja.md

@@ -1,17 +1,17 @@
 # shinten-ship
 
-**shinten の出荷デスク。封じた住所を、送り状を作る場所でだけ開く。**
+**shinten の出荷デスク。暗号化された住所を、送り状を作る場所でだけ復号する。**
 
-[shinten](https://github.com/eucassoc/shinten) で配送先を封じている店舗は、
-注文ごとに郵便番号と封筒しか持ちません。それでも誰かが送り状を印字します。
-shinten-ship はその誰かの道具です。出荷担当の端末で動き、各注文の封筒を
-その端末の秘密鍵で開き、配送業者の送り状ソフトがそのまま受け付ける取込ファイルを
+[shinten](https://github.com/eucassoc/shinten) で配送先を暗号化している店舗は、
+注文ごとに郵便番号と暗号文しか持ちません。それでも誰かが送り状を印字します。
+shinten-ship はその誰かの道具です。出荷担当の端末で動き、各注文の暗号文を
+その端末の秘密鍵で復号し、配送業者の送り状ソフトがそのまま受け付ける取込ファイルを
 書きます。住所が平文で存在するのはその端末の上、取込ファイルがある間だけで、
 その後は消えます。
 
 [English](README.md)
 
-- 注文のエクスポート(注文ID、郵便番号、封筒、送り状に要る平文項目: 品名、個数、
+- 注文のエクスポート(注文ID、郵便番号、暗号文、送り状に要る平文項目: 品名、個数、
   日付、時間帯、保冷)を JSON、JSON Lines、CSV で読みます。
 - ヤマト運輸 B2クラウド(基本レイアウト、97項目、位置固定)と日本郵便
   ゆうパックプリントR(項目名付きの列。フィルタで一対一に対応付け)の取込 CSV を
@@ -21,15 +21,15 @@ shinten-ship はその誰かの道具です。出荷担当の端末で動き、
   記録します。証跡ログに後から載せられる形です。
 - デスク用の CLI と、デスクを動かすエージェント向けの MCP サーバー。
 
-デスクの秘密鍵は端末から出ません。デスクが複数ある店舗や外部の倉庫は、封筒の
+デスクの秘密鍵は端末から出ません。デスクが複数ある店舗や外部の倉庫は、暗号化の
 宛先が増えるだけです。バックアップ鍵をオフラインに置いてください。失った鍵
-だけに封じた封筒は、誰にも開けません。
+だけで暗号化した内容は、誰にも復号できません。
 
 ## 準備
 
 ```sh
 npm install -g shinten-ship
-shinten keygen -o desk.json         # shinten の鍵。公開側を店舗のフォームの宛先として公開する
+shinten keygen -o desk.json         # shinten の鍵。公開鍵を店舗のフォームの暗号化の宛先として公開する
 ```
 
 `ship.json` に差出人と業者のアカウントを書きます。
@@ -43,8 +43,8 @@ shinten keygen -o desk.json         # shinten の鍵。公開側を店舗のフ
 }
 ```
 
-`recipients` は、店舗のフォームが封じるはずの公開鍵を、この発送窓口が承認したものです。
-他の鍵にも封じられた注文や、これらの鍵が欠けた注文は、店舗のサイトの鍵一覧が
+`recipients` は、店舗のフォームが暗号化に使うはずの公開鍵を、この発送窓口が承認したものです。
+他の鍵でも暗号化された注文や、これらの鍵が欠けた注文は、店舗のサイトの鍵一覧が
 差し替えられたことを意味します。ラベルは一つも作られず、`labels` は STOP で終わります。
 同じ鍵で `shinten watch -r` を定期的に店舗の鍵一覧に向けて実行すれば、注文が来る前に
 差し替えを見つけられます。
@@ -55,11 +55,11 @@ shinten keygen -o desk.json         # shinten の鍵。公開側を店舗のフ
 
 ## 注文
 
-注文のエクスポートは、店舗が既に持っているもの(平文項目と封筒)に、送り状に
+注文のエクスポートは、店舗が既に持っているもの(平文項目と暗号文)に、送り状に
 書く内容を加えたものです。次のどの形でも読めます。
 
 ```json
-[{ "id": "A-1", "postalCode": "150-0001", "envelope": { "...": "保存されている shinten の封筒" },
+[{ "id": "A-1", "postalCode": "150-0001", "envelope": { "...": "保存されている shinten の暗号文" },
    "item": "雑貨", "count": 1, "deliveryDate": "2026-04-03", "timeSlot": "14-16", "cool": "chilled" }]
 ```
 
@@ -79,12 +79,12 @@ shinten-ship labels --carrier yamato-b2 -k desk.json -c ship.json -o labels.csv
 shinten-ship purge labels.csv
 ```
 
-このデスクで開けない封筒や、業者の項目に収まらない注文(ヤマトで住所が64バイト
+このデスクの鍵で復号できない暗号文や、業者の項目に収まらない注文(ヤマトで住所が64バイト
 超、業者にない時間帯)は除外して報告し、残りを書き出します。ファイルは業者の
 ソフトが読む CP932、CRLF です。
 
 記録は `~/.shinten-ship/records.jsonl`(または `SHINTEN_SHIP_RECORDS`)に
-追記されます。各ファイルのダイジェスト、含まれる注文の ID と封筒のダイジェスト、
+追記されます。各ファイルのダイジェスト、含まれる注文の ID と暗号文のダイジェスト、
 消去の事実です。住所が記録に入ることはありません。
 
 ## MCP
@@ -97,7 +97,7 @@ shinten-ship purge labels.csv
 | ツール | 内容 |
 |---|---|
 | `carriers` | このデスクが書ける形式と、各業者のソフトでの読み込み方 |
-| `make_labels` | 注文の封筒を開き、送り状ファイルを指定パスに書く |
+| `make_labels` | 注文の暗号文を復号し、送り状ファイルを指定パスに書く |
 | `purge` | アップロード後に送り状ファイルを消し、ダイジェストを記録する |
 
 ## 業者の形式
@@ -109,6 +109,25 @@ shinten-ship purge labels.csv
 
 業者の形式は業者の都合で変わります。形式は `src/carriers/` の1ファイルです。
 
+## 例
+
+[shinten の web-shop の例](https://github.com/eucassoc/shinten/tree/main/examples/web-shop)
+で、架空のネットショップの出荷担当の端末を動かせます。暗号化された注文からヤマト運輸
+B2クラウドの取込ファイルを作り、印刷後に削除し、サイトが承認していない鍵を配っていた
+ときには止まります。流れは[約2分の動画](https://github.com/eucassoc/shinten/blob/main/examples/web-shop/demo.mp4)で見られます。
+
+受付から復号、削除までの各手順は [deedlog](https://github.com/eucassoc/deedlog) で記録し、
+二つの連署サーバーが連署します。そのため、例を動かすには `dlog` コマンドが必要です
+（Go が必要です）。
+
+```sh
+go install github.com/eucassoc/deedlog/cmd/dlog@latest
+
+git clone https://github.com/eucassoc/shinten && cd shinten/examples/web-shop
+npm install
+npm start          # http://127.0.0.1:8800/
+```
+
 ## 開発
 
 ```sh

package/README.md

@@ -115,6 +115,27 @@ and each purge. No address is ever in a record.
 Carrier formats change on the carriers' schedule; a format is one file
 under `src/carriers/`.
 
+## Example
+
+[shinten's web-shop example](https://github.com/eucassoc/shinten/tree/main/examples/web-shop)
+runs the desk on a fictional shop: Yamato B2 Cloud labels from encrypted
+orders, the file deleted after printing, and the stop when the site has
+served a key the desk never approved.
+[A two-minute video](https://github.com/eucassoc/shinten/blob/main/examples/web-shop/demo.mp4)
+walks through it.
+
+Each step, from receipt to decryption and deletion, is also recorded with
+[deedlog](https://github.com/eucassoc/deedlog) and cosigned by two witnesses,
+so running the example needs its `dlog` command (Go required):
+
+```sh
+go install github.com/eucassoc/deedlog/cmd/dlog@latest
+
+git clone https://github.com/eucassoc/shinten && cd shinten/examples/web-shop
+npm install
+npm start          # http://127.0.0.1:8800/
+```
+
 ## Development
 
 ```sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shinten-ship",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "The shipping desk for shinten: opens sealed delivery addresses on the desk's own device and writes the carrier's label-import CSV, so the store never holds an address in the clear.",
   "license": "Apache-2.0",
   "repository": "github:eucassoc/shinten-ship",