DTO Attestation

Supper App Service API Models - Attestation Model

/v1/attestation/get-challenge

• Type: HTTP/1.1 (REST APIs), phục vụ qua grpc-gateway. Cùng hiện thực với gRPC AttestationService/GetChallenge.
• SSL: v1.3 or higher
• Connection: Client to Server - “keep-alive”
• Method: GET
• Hearders:
  • Content-Type: ‘application/json; charset=utf-8’
  • X-Api-Tracking-ID: <device-identify-string>
  • X-Api-Request-ID: <unique-string>
  • X-Api-Idempotency-Key: <unique-string>
  • X-Api-Timestamp: <unix-timestamp>

Quick Reference

• [Request Model] - No require
• Response Model

Get Challenge Response Model

type GetChallengeResponse struct {
    Code int `json:"code" binding:"required"`
    Message string  `json:"message"`
    Payload *GetChallengePayload `json:"payload"`
}

• code và message luôn có trong body. message là chuỗi rỗng khi thành công.
• payload luôn có trong body. Là null khi lỗi, và là object khi thành công.

Ví dụ response

Thành công (HTTP 200):

{"code":0,"message":"","payload":{"challengeJwt":"eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9..."}}

Lỗi hệ thống (HTTP 200, mã nghiệp vụ trong body):

{"code":1999,"message":"Lỗi hệ thống","payload":null}

Khoảng trắng giữa các token không thuộc contract. Client phải parse JSON, không so sánh chuỗi.

Attestation Dependent Models

Get Challenge Response Payload

type GetChallengePayload struct {
    ChallengeJwt string `json:"challengeJwt"`
}

Field Descriptions:

• ChallengeJwt (string): JWT EdDSA ký bằng Preshare Key. Claim gồm challenge (32 byte ngẫu nhiên, base64), iat và exp (= iat + 5 phút). Server không lưu challenge. Client dùng chuỗi này trong attestation.challengeJwt của /v1/auth/init-session (IOS).
• Lỗi nghiệp vụ: code: 1999 (HTTP 200) khi lỗi hệ thống. Mã lỗi xem ResponseErrorCode.md.

Attestation Model Relationships

• GetChallengeResponse -> Challenge Payload
• Init-session dùng challengeJwt theo DTO Authentication

Thay đổi wire (2026-10-14)

• message luôn có (rỗng khi thành công). Trước đó bị bỏ khi rỗng.
• payload là null khi lỗi. Trước đó bị bỏ.
• Content-Type là application/json. Trước đó là application/json; charset=UTF-8.
• Client iOS cần xác nhận chấp nhận các thay đổi này trước khi release (xem memory/histories/2026-10-14_IMPLEMENT_ATTESTATION_GRPC_GATEWAY_SUMMARY.md).