VirMesh Protocol

Appearance

me.virmesh.handle.updateHandle ​

署名済み handle payload を保存または更新します。

player 本人署名済みの handle payload を保存する private action です。 tombstone 化済み account の handle 更新は受理されません。

draft

Endpoint

Method
POST
Path
/private/me.virmesh.handle.updateHandle
Auth
required
Host
VirMesh.HandleServer, optional VirMesh.PlayerServer

Request schema

payload.idstringRequired

non-empty string。署名検証で owner id として使います。

payload.primaryHandlestringRequired

primary handle です。

payload.secondaryHandlesstring[]Required

secondary handle 一覧です。lower-case 正規化後に重複できません。

payload.playerServerstringRequired

absolute http または https URL を送ります。

payload.updated_atintegerRequired

non-negative epoch second を送ります。

signaturestringRequired

canonical JSON of payload に対する署名です。

Request example

{
  "payload": {
    "id": "medi:player:ed25519:base64-public-key",
    "primaryHandle": "alice@virmesh.me",
    "secondaryHandles": [
      "alice@example.com"
    ],
    "playerServer": "https://ps.example.com/",
    "updated_at": 1711800000
  },
  "signature": "base64-signature-of-payload"
}

Responses

200
status+me.virmesh.success.handleUpdated

handle record が保存または更新されたことを示します。

me.virmesh.handle.updateHandle が正常終了し、 指定した player の handle record が保存または更新されたときに返します。

handle updated

{
  "status": "status+me.virmesh.success.handleUpdated"
}
400
status+me.virmesh.json.invalid_json

request body が JSON として解釈できないことを示します。

この status は body が壊れている、または JSON parser が受理できない形式で送られた場合に返ります。

Status payload

payload.messagestringRequired

実装依存の詳細メッセージです。

malformed json

{
  "status": "status+me.virmesh.json.invalid_json",
  "payload": {
    "message": "Request body must be valid JSON."
  }
}
400
status+me.virmesh.json.invalid_private_request

private request envelope の形式が不正であることを示します。

この status は private route が期待する from, payload, signature などの envelope 要件を満たさない場合に返ります。

Status payload

payload.messagestringRequired

実装依存の詳細メッセージです。

invalid private envelope

{
  "status": "status+me.virmesh.json.invalid_private_request",
  "payload": {
    "message": "Private request must contain the expected envelope fields."
  }
}
400
status+me.virmesh.json.unexpected_fields

許可されていない field が request に含まれていることを示します。

この status は strict validation が有効な route に未知の top-level field または payload field を送った場合に返ります。

Status payload

payload.messagestringRequired

実装依存の詳細メッセージです。

unexpected request fields

{
  "status": "status+me.virmesh.json.unexpected_fields",
  "payload": {
    "message": "Request contains unknown fields that are not allowed by this route."
  }
}
400
status+me.virmesh.json.invalid_payload

`payload`がactionの期待する形式ではないことを示します。

リクエストデータ自体はJSON objectとして解釈できたものの、 期待する形式と一致しない場合に使います。

Status payload

payload.messagestringRequired

検証に失敗した理由を表す詳細メッセージです。

invalid payload

{
  "status": "status+me.virmesh.json.invalid_payload",
  "payload": {
    "message": "送信されたペイロードが正しい形式ではありません。"
  }
}
400
status+me.virmesh.http.invalid_url

URL として解釈できない値が送られたことを示します。

この status は URL field が absolute URL の要件を満たさない場合に返ります。 updateHandle では payload.playerServer の検証失敗に使われます。

Status payload

payload.messagestringRequired

実装依存の詳細メッセージです。

playerServer is invalid

{
  "status": "status+me.virmesh.http.invalid_url",
  "payload": {
    "message": "payload.playerServer must be an absolute http or https URL."
  }
}
400
status+me.virmesh.handle.invalid_timestamp

`updated_at` が有効な epoch second ではないことを示します。

この status は payload.updated_at が non-negative integer として解釈できない場合に返ります。

Status payload

payload.messagestringRequired

実装依存の詳細メッセージです。

updated_at is invalid

{
  "status": "status+me.virmesh.handle.invalid_timestamp",
  "payload": {
    "message": "payload.updated_at must be a non-negative integer epoch second."
  }
}
400
status+me.virmesh.handle.timestamp_in_future

`updated_at` が server 時刻より未来であることを示します。

この status は handle update の timestamp が server の現在時刻を超えている場合に返ります。

Status payload

payload.messagestringRequired

実装依存の詳細メッセージです。

updated_at is in the future

{
  "status": "status+me.virmesh.handle.timestamp_in_future",
  "payload": {
    "message": "payload.updated_at must not be in the future."
  }
}
400
status+me.virmesh.handle.timestamp_out_of_range

`updated_at` が freshness window を超えて古いことを示します。

この status は handle update の timestamp が server の許容範囲より古い場合に返ります。

Status payload

payload.messagestringRequired

実装依存の詳細メッセージです。

updated_at is too old

{
  "status": "status+me.virmesh.handle.timestamp_out_of_range",
  "payload": {
    "message": "payload.updated_at is older than the accepted freshness window."
  }
}
401
status+me.virmesh.key.invalid_signature

署名の形式が不正、または署名検証に失敗したことを示します。

この status は署名文字列が base64 として不正な場合と、 復元できた署名が検証に失敗した場合に使われます。

Status payload

payload.messagestringRequired

実装依存の詳細メッセージです。

signature verification failed

{
  "status": "status+me.virmesh.key.invalid_signature",
  "payload": {
    "message": "Signature verification failed."
  }
}
403
status+me.virmesh.handle.player_not_allowed

指定した player が handle update を実行できないことを示します。

この status は認証済み player が対象 record の更新ポリシーを満たしていない場合に返ります。

Status payload

payload.messagestringRequired

実装依存の詳細メッセージです。

player is not allowed

{
  "status": "status+me.virmesh.handle.player_not_allowed",
  "payload": {
    "message": "The authenticated player is not allowed to update this handle record."
  }
}
409
status+me.virmesh.handle.already_used

指定した handle が他の record で使用中であることを示します。

この status は primary または secondary handle が既存 record と衝突した場合に返ります。

Status payload

payload.messagestringRequired

実装依存の詳細メッセージです。

handle is already used

{
  "status": "status+me.virmesh.handle.already_used",
  "payload": {
    "message": "One or more handles are already assigned to another player."
  }
}
409
status+me.virmesh.handle.stale_update

既存 record より古い handle update であることを示します。

この status は保存済み record より古い updated_at を送った場合に返ります。

Status payload

payload.messagestringRequired

実装依存の詳細メッセージです。

handle update is stale

{
  "status": "status+me.virmesh.handle.stale_update",
  "payload": {
    "message": "A newer handle record already exists."
  }
}
409
status+me.virmesh.handle.timestamp_conflict

同一 `updated_at` に対して異なる handle payload が送られたことを示します。

この status は保存済み record と同じ updated_at を使いながら、内容が一致しない場合に返ります。

Status payload

payload.messagestringRequired

実装依存の詳細メッセージです。

same timestamp with different content

{
  "status": "status+me.virmesh.handle.timestamp_conflict",
  "payload": {
    "message": "A different handle payload already exists for this updated_at value."
  }
}
410
status+me.virmesh.account.disabled

対象 account が tombstone 化済みであり、有効な主体または参照先として扱えないことを示します。

この status は account が disable 済みで、以後の更新、social 操作、migration、 公開 profile / handle 解決の対象として受理されない場合に返ります。 通常は HTTP 410 Gone と組み合わせて返します。

Status payload

payload.messagestringRequired

実装依存の詳細メッセージです。

account disabled

{
  "status": "status+me.virmesh.account.disabled",
  "payload": {
    "message": "The requested account has been disabled and tombstoned."
  }
}