PC のクライアント

PC に常駐するプログラム。サーバーへは外向きの HTTPS だけで接続する（PC との通信）。外からの接続は受けない。 ローカルのことは、ローカルだけが決める（Cloud Paper の仕組み）。

10.1 コマンド

agent            # 常駐して動く
agent open       # 設定画面をブラウザで開く
agent install    # ログイン時に自動で起動するよう登録
agent uninstall  # 登録を外す

• 設定の置き場は CPP_DIR（既定はユーザーの設定フォルダの cloudpaper。前の名前の kobesoft-cloud-paper のフォルダーが残っていて、新しいフォルダーが無ければ、前のものを使う）。
• open は admin.token を読み、http://127.0.0.1:8731/?t=<トークン> を開く。先に agent を起動しておく。
• install:
  • macOS: ~/Library/LaunchAgents/jp.co.kobesoft.cloudpaper-agent.plist（KeepAlive・RunAtLoad）を作って launchctl load。
  • Linux: systemd のユーザーユニット cloudpaper-agent.service（Restart=always）を作って有効化。
  • Windows: タスク CloudPaperClient（ログオン時）。
• 起動すると、設定画面と（空いていれば）ローカル API を開く。トークンはログに書かない。

10.2 設定画面（127.0.0.1:8731）

画面と操作

画面は / の 1 枚。節は上から次のとおり。操作はすべて POST で、終わると / へ戻る。

節	操作（パス）
接続	接続（/connect）：契約 ID か URL を入れる。契約 ID は <ID>.cloudpaper.appz.jp に展開。URL は https のみ（開発のループバックだけ http）。コードと承認ページが出る。貼り付けによる接続（/bundle/preview・/bundle/apply・/bundle/cancel）。切断（/disconnect）。更新の適用（/update/apply）・自動更新の切り替え（/update/auto）
プリンター	追加（/printers/add：OS のキューを選ぶ。用紙・トレイ・両面・カラー・安全印刷（既定で入））。プロファイルの保存・削除（/printers/profile・/printers/profile/delete）。上限（/printers/limits）。安全印刷（/printers/safe）。停止・再開・削除（/printers/pause・/resume・/remove）
取り込み	追加（/intake/add）。上限（/intake/limits）。停止・再開・削除。スキャン（/intake/scan）。スキャナーの検出（/scanners/find）
着信番号（モデム）	追加（/callers/add）・送るの切り替え（/callers/toggle）・削除
ドットで直接送る	追加（/printers/raster）・テストラベル（/printers/testlabel）
FAX 送信	追加（/printers/fax。CUPS・HylaFAX・Windows の FAX サービス）
ログ	画面（GET /log）・記録（GET /log/entries?level=）・ダウンロード（GET /log/download）・接続の診断（POST /log/diagnose）。10.13
このPCのアプリから印刷	アプリを許可（/apps/allow）・取り消し（/apps/revoke）

• ほかに GET /static/admin.js。
• 画面に出す上限は、実際にかかる値（app.EffectiveLimits）。ラベルは 100 ページ、FAX は 30 ページが既定（以前は書類の値が出ていた誤りを直した）。
• 契約の PC の数・承認の状態・失効（「サーバーから接続が解除されました」）・お知らせ（最新 50 件）も画面に出る。

10.3 ローカル API（127.0.0.1:8732）

メソッド・パス	内容
GET /v1/printers	そのアプリに許したプリンター。{"printers":[{"ref","kind","profiles","default"}]}
POST /v1/jobs	multipart。printer・file（PDF）・profile・copies・fax_to。→ {"state":"done"}。断ると 422 {"state":"refused","error":"…"}

• Authorization: Bearer cpl_…（アプリごと）。トークンは設定画面の「アプリを許可」で作り、一度だけ表示する。PC にはハッシュだけを残す。アプリには使えるプリンターを選ぶ。
• Host が 127.0.0.1・localhost でない、または Origin がある、または Sec-Fetch-Site が none 以外なら 403（ブラウザからの要求を断る）。
• 許していないプリンターは 403、file が無ければ 422。本文は 50 MiB + 1 MiB まで。
• 署名は無い。サーバーの指示と同じ検査・同じ上限を通る（HandleLocal）。起源は local。

10.5 印刷

• macOS・Linux: CUPS の lp（引数は配列。シェルを通さない）。-n（部数）・media・InputSlot（トレイ）・sides（両面）・fit-to-page・print-color-mode=monochrome・プロファイルの拡張オプション。値は [A-Za-z0-9._-] 系だけ。
• Windows: 同梱の SumatraPDF（-print-to・-silent）。キュー一覧は PowerShell の Get-Printer。
• 用紙・トレイ・オプションは、ドライバーが自分で出す一覧（lpoptions -l）と照らして、プロファイルに保存するときに確かめる。独自の用紙は Custom.<幅>x<高さ><mm|cm|in|pt>。
• プロファイル: 名前（40 文字まで）ごとに用紙・トレイ・両面・カラー・拡大（fit｜none）・拡張オプション。サーバーが指定できるのは名前だけ。
• 種類: document｜label（ラベルの既定の上限は大きい）。
• 同じ名前のプリンターを足すと置き換える。変更すると、サーバーにプリンターの一覧を知らせ直す。

ドットでの直送（ラベル・感熱・ドットインパクト）

PDF を PDFium で画像にして白黒にし、プリンターの命令に変えて送る。

プロトコル	対象	主な設定
brother-ql	Brother QL	用紙（12 29 38 50 54 62 と、17x54 29x90 62x29 など定型）。300 dpi。左右反転（mirror）
zpl	ZPL のラベルプリンター	幅 10〜200 mm・高さ 0〜600 mm（0 はページに合わせる）・203/300/600 dpi
escpos	ESC/POS の感熱	幅 58 か 80 mm・カット
escp	ESC/P 24 ピン ドットインパクト	幅 50〜330 mm・改ページ（Cut）

• 送り方（transport）: tcp（ホスト:ポート。ポート省略は 9100）｜cups-raw（キュー名）｜device（/dev/usb/lp0 のような名前）。
• 共通: ディザ・しきい値。テストラベルで向きを確かめ、必要なら「左右を反転」を切り替える。
• 絵にするときの上限: 1 回 50 ページ・1 ページ 4000 万画素（raster.MaxPages・MaxPixels）。

安全印刷（SafePrint）

プリンターごとの設定。PDF を 300 dpi の画像にしてから PDF にし直して印刷する。ファイルの中身（フォント・構造）がプリンターのドライバーに届かない。ドットの直送には要らない。

• プリンターを新しく登録するときは、既定で入（登録の画面のチェックが最初から付いている。外せる）。すでに保存してある設定は、そのまま。
• FAX 機は、常に画像に描き直した文書（200 dpi）を FAX のサービスへ渡す（HylaFAX などは PDF を Ghostscript で変換し、Ghostscript には脆弱性の歴史が長いため）。FAX 機ごとの切り替えは無い。

10.6 FAX 送信

• プリンターとして登録する（種類 fax）。送り方:
  • cups: 数字を phone オプションにとる CUPS の FAX キュー（lp -d <キュー> -o phone=<番号>）。
  • hylafax: sendfax -n -d <番号> [-h <ホスト>] <ファイル>。
  • 複合機の FAX 印刷ドライバー（番号の入力画面が出るもの）は使えない。
  • windows: Windows の FAX サービス（FaxComEx）。PDF を PDFium で描き、FAX 用の TIFFにして、固定の PowerShell で FaxServer.Connect → FaxDocument.ConnectedSubmit を呼ぶ。target は FAX サーバー名（空はこの PC）。文書・番号は環境変数で渡す。サービスが受け付けた時点で成功とする。実機（FAX モデムと Windows の FAX サービスのある PC）では未確認。
• この PC の利用者が決めること: 許可する番号の先頭（AllowPrefixes）・国際（既定は不可）・有料番号（0990 0570 0180 0170 0900 0910。既定は不可）・1 時間の発信回数・同じ番号への 1 日の回数。
• 番号は国内の形に直す（+81… は 0…）。国際は +・00・010 で始まるもの。
• 1 回 1 部。ログ・記録には末尾 4 桁だけ。

10.7 取り込み

共通

• 読むのは PDF・JPEG・PNG・TIFF だけ（先頭のバイトで判定。名前・拡張子は信用しない）。
• 送り先（sink）: inbox（サーバーの受け口）｜folder（別のフォルダ。上書きしない・書類の名前をパスに使わない）｜printer（登録したプリンター。PDF だけ）。
• 上限（既定は 上限）は取り込み元ごと。超えると取り込み元を自動停止し、人が再開するまで止まる。再起動で数えは戻らない（intake.json）。同じ内容は 24 時間送らない。
• 受け口へ送れない（停止・容量・上限）ときは、ファイルは残し、後で再試行する。

フォルダ監視

設定	内容
フォルダ	絶対パス。実在・フォルダ・ドライブ直下でない。システム・設定・鍵の場所（/etc /System /Library /usr C:\Windows C:\Program Files AppData、ホームの隠しフォルダ（.ssh など）、macOS の Library、ホームそのもの、エージェントの設定フォルダ）は選べない
後の処理	move（既定。同じフォルダの 取り込み済み へ）｜delete｜keep。失敗は 取り込み失敗 へ
見る間隔・待ち	2 秒ごとに見る。大きさと更新時刻が 2 回変わらず、10 秒静かになってから読む
読まないもの	サブフォルダ・シンボリックリンク・隠しファイル・~ 始まり・Thumbs・desktop.ini・.tmp .part .partial .crdownload .lock .filepart .download .swp .db

ネットワーク共有でも動くよう、OS のイベントでなくポーリングにしている。 取り込み元どうし・送り先のフォルダと監視フォルダが重なる設定は断る。

プリセット	種類	追加の動き
scansnap	scan	連番の画像（名前_001.jpg…）を 1 つの PDF に束ねる。単独の JPEG・PNG を 1 ページの PDF にする。ScanSnap の「フォルダへ保存」を指す
brother	scan	同上。Brother の「スキャン to ネットワークフォルダ」を指す
fax	fax	画像・TIFF を PDF にする（FAX の TIFF は PDF に直す。直せない TIFF はそのまま送る）。FAX の受信フォルダを指す
generic	file	変換なし

FAX の送信元の番号: 「番号を取り出す正規表現」（かっこ 1 組）を PC の利用者が書いたときだけ、ファイル名から取って X-CPP-Caller に付ける。

スキャナー

種類を 3 つから選ぶ。取り込み元として登録し、設定画面の「スキャン」で 1 回ずつ実行する。

種類	内容
eSCL（Brother など）	アドレスは社内ネットワーク（プライベートアドレス・ループバック）だけ。リンクローカル（169.254.…）は不可。自動スキャン（原稿を入れると自分で始める）を選べる。eSCL だけ
SANE	scanimage を使う。scanimage -L が出すデバイスだけ（Linux・macOS）
WIA	固定の PowerShell を使う。デバイス ID・解像度・フォルダは環境変数で渡す（Windows。実機未確認）

設定: 台・フィーダー、カラー（RGB24｜Grayscale8｜BlackAndWhite1）、75〜1200 dpi（既定 300）、両面。 1 回のスキャンは合計 80 MiB まで。JPEG を PDF にまとめる。

10.8 着信番号

• モデムをシリアルポートで読む。macOS・Linux は /dev/tty.*・/dev/cu.*・ttyUSB など、Windows は COM ポート（\\.\COMn を開く。一覧はレジストリ HKLM\HARDWARE\DEVICEMAP\SERIALCOMM。8N1・DTR 有効・SetCommState・SetCommTimeouts）。
• 読むだけ。 書くのは「発信者番号表示を有効にする」短い一覧の命令だけ（AT+VCID=1 AT#CID=1 AT*ID1 AT%CCID=1 AT+VCID=1;、または何も書かない）。発信・応答・切断はしない。
• 初期化コマンドの指定が「自動」なら、AT+VCID=1 → AT#CID=1 → AT*ID1 の順に送り、モデムが OK と答えた最初のものを使う（ERROR・2 秒の無応答なら次へ）。どれも通らなければ警告を出して待ち受けは続ける（すでに有効なモデムのため）。
• 読み取る形: NMBR = …・CALLER NUMBER: …・CALLER ID: …・CID = …・+CLIP: "…"（= と :、行末が CR・LF・CRLF のどれでも）。DATE・TIME・NAME も読む。番号が P（非通知）なら withheld、O（通知不可）なら unavailable で、番号は送らない。
• ポートを他のソフト（FAX のドライバー・HylaFAX など）が使っているときは、開けず、ログと設定画面（モデムの横）に「他のソフトが使用中」と出し、1 分ごとに開き直す（Windows は共有なしで開く。macOS・Linux は flock＋TIOCEXCL）。ログは状態が変わったときだけ書く。
• 着信の番号は、ログには真ん中を伏せて書く（03******78）。
• 速度は 9600・19200・38400・57600・115200（既定）。
• 登録は「送らない」で始まる。 PC の利用者が「送る」にしたときだけサーバーへ送る。
• 暴走を止める: 1 分 20 件・1 時間 200 件を超えると止まる。1 行は 1 KiB まで（超えたら読み取りを終える）。
• 送信は 6 回まで、10・20・30… 秒の間隔で試す。サーバーが断ったら（ErrRefused）やめる。古い着信は捨てる。ポートが無いときは 1 分ごと、切れたときは 30 秒後に再接続する。

10.9 更新

• ビルドに update.Version と update.ReleasePub（リリースの公開鍵）を埋め込む（運用）。公開鍵が無いと更新は動かない。
• 2 分後に最初の確認、以後 6 時間ごと。確認の結果（最新・新しい版あり・失敗）はログに残る。新しい版が見つかり、利用者が自動更新を切っていなければ、取りに行って入れ替える。切っていれば設定画面に出る。
• 版・大きさ・ハッシュは署名されたマニフェストだけを信じる。大きさとハッシュが合わなければ入れない。上限 120 MiB。
• 入れ替えたら再起動する（macOS の launchd・Linux の systemd が起動し直す。Windows は新しいプログラムを自分で起動する）。

10.12 キルスイッチ

「すべて停止」（トレイ）は、全プリンターと全取り込み元を止める。再開は人がする。サーバー側のキルスイッチは、パネルの PC の停止・テナントの停止。