api

Documentation

Overview

Package api defines the JSON-RPC API between the browser and the server as well as between mobile devices and the server.

Index

• Constants
• type AcceptTypes
  • func (a AcceptTypes) AddAcceptTypes(types ...string)
• type CSRFResponse
• type CheckCodeStatusRequest
• type CheckCodeStatusResponse
• type ErrorReturn
  • func Error(err error) *ErrorReturn
  • func Errorf(msg string, vars ...interface{}) *ErrorReturn
  • func InternalError() *ErrorReturn
  • func (e *ErrorReturn) WithCode(code string) *ErrorReturn
• type ExpireCodeRequest
• type ExpireCodeResponse
• type IssueCodeRequest
• type IssueCodeResponse
• type VerificationCertificateRequest
• type VerificationCertificateResponse
• type VerifyCodeRequest
  • func (v *VerifyCodeRequest) GetAcceptedTestTypes() (AcceptTypes, error)
• type VerifyCodeResponse

Constants

const (
	// TestTypeConfirmed is the string that represents a confirmed covid-19 test.
	TestTypeConfirmed = "confirmed"
	// TestTypeLikely is the string that represents a clinical diagnosis.
	TestTypeLikely = "likely"
	// TestTypeNegative is the string that represents a negative test.
	TestTypeNegative = "negative"

	// error_code definitions for the APIs.
	// General
	ErrUnparsableRequest = "unparsable_request"
	ErrInternal          = "internal_server_error"

	// Verify API responses
	// ErrVerifyCodeInvalid indicates the code entered is unknown or already used.
	ErrVerifyCodeInvalid = "code_invalid"
	// ErrVerifyCodeExpired indicates the code provided is known to the server, but expired.
	ErrVerifyCodeExpired = "code_expired"
	// ErrVerifyCodeNotFound indicates the code does not exist on the server/realm.
	ErrVerifyCodeNotFound = "code_not_found"
	// ErrVerifyCodeUserUnauth indicates the code does not belong to the requesting user.
	ErrVerifyCodeUserUnauth = "code_user_unauthorized"
	// ErrUnsupportedTestType indicates the client is unable to process the appropriate test type
	// in thise case, the user should be directed to upgrade their app / operating system.
	// Accompanied by an HTTP status of StatusPreconditionFailed (412).
	ErrUnsupportedTestType = "unsupported_test_type"
	// ErrInvalidTestType indicates the client says it supports a test type this server doesn't
	// know about.
	ErrInvalidTestType = "invalid_test_type"

	// Certificate API responses
	// ErrTokenInvalid indicates the token provided is unknown or already used
	ErrTokenInvalid = "token_invalid"
	// ErrTokenExpired indicates that the token provided is known but expired.
	ErrTokenExpired = "token_expired"
	// ErrHMACInvalid indicates that the HMAC that is being signed is invalid (wrong length)
	ErrHMACInvalid = "hmac_invalid"
)

Types

type AcceptTypes

type AcceptTypes map[string]struct{}

AcceptTypes is a map of string to struct.

func (AcceptTypes) AddAcceptTypes

func (a AcceptTypes) AddAcceptTypes(types ...string)

AddAcceptTypes takes a list of acceptable types and converts it to a map.

type CSRFResponse

type CSRFResponse struct {
	CSRFToken string `json:"csrftoken"`
	Error     string `json:"error"`
	ErrorCode string `json:"errorCode"`
}

CSRFResponse is the return type when requesting an AJAX CSRF token.

type CheckCodeStatusRequest

type CheckCodeStatusRequest struct {
	// UUID is a handle which allows the issuer to track status of the issued verification code.
	UUID string `json:"uuid"`
}

CheckCodeStatusRequest defines the parameters to request the status for a previously issued OTP code. This is called by the Web frontend. API is served at /api/checkcodestatus

type CheckCodeStatusResponse

type CheckCodeStatusResponse struct {
	// Claimed is true if a user has used the OTP code to get a token via the VerifyCode api.
	Claimed bool `json:"claimed"`

	// ExpiresAtTimestamp represents Unix, seconds since the epoch. Still UTC.
	// After this time the code will no longer be accepted and is eligible for deletion.
	ExpiresAtTimestamp int64 `json:"expiresAtTimestamp"`

	// LongExpiresAtTimestamp repesents the time when the long code expires, in
	// UTC seconds since epoch.
	LongExpiresAtTimestamp int64 `json:"longExpiresAtTimestamp,omitempty"`

	Error     string `json:"error,omitempty"`
	ErrorCode string `json:"errorCode,omitempty"`
}

CheckCodeStatusResponse defines the response type for CheckCodeStatusRequest.

type ErrorReturn

type ErrorReturn struct {
	Error     string `json:"error"`
	ErrorCode string `json:"errorCode"`
}

ErrorReturn defines the common error type.

func Error

func Error(err error) *ErrorReturn

Error wraps the error into an API error.

func Errorf

func Errorf(msg string, vars ...interface{}) *ErrorReturn

Errorf creates an ErrorReturn w/ the formateed message.

func InternalError

func InternalError() *ErrorReturn

InternalError constructs a generic internal error.

func (*ErrorReturn) WithCode

func (e *ErrorReturn) WithCode(code string) *ErrorReturn

WithCode adds an error code to an ErrorReturn

type ExpireCodeRequest

type ExpireCodeRequest struct {
	// UUID is a handle which allows the issuer to track status of the issued verification code.
	UUID string `json:"uuid"`
}

ExpireCodeRequest defines the parameters to request that a code be expired now. This is called by the Web frontend. API is served at /api/expirecode

type ExpireCodeResponse

type ExpireCodeResponse struct {
	// ExpiresAtTimestamp represents Unix, seconds since the epoch. Still UTC.
	// After this time the code will no longer be accepted and is eligible for deletion.
	ExpiresAtTimestamp int64 `json:"expiresAtTimestamp"`

	// LongExpiresAtTimestamp repesents the time when the long code expires, in
	// UTC seconds since epoch.
	LongExpiresAtTimestamp int64 `json:"longExpiresAtTimestamp,omitempty"`

	Error     string `json:"error,omitempty"`
	ErrorCode string `json:"errorCode,omitempty"`
}

ExpireCodeResponse defines the response type for ExpireCodeRequest.

type IssueCodeRequest

type IssueCodeRequest struct {
	SymptomDate string `json:"symptomDate"` // ISO 8601 formatted date, YYYY-MM-DD
	TestDate    string `json:"testDate"`
	TestType    string `json:"testType"`
	// Offset in minutes of the user's timezone. Positive, negative, 0, or omitted
	// (using the default of 0) are all valid. 0 is considered to be UTC.
	TZOffset int    `json:"tzOffset"`
	Phone    string `json:"phone"`
}

IssueCodeRequest defines the parameters to request an new OTP (short term) code. This is called by the Web frontend. API is served at /api/issue

type IssueCodeResponse

type IssueCodeResponse struct {
	// UUID is a handle which allows the issuer to track status of the issued verification code.
	UUID string `json:"uuid"`

	// The OTP code which may be exchanged by the user for a signing token.
	VerificationCode string `json:"code"`

	// ExpiresAt is a RFC1123 formatted string formatted timestamp, in UTC.
	// After this time the code will no longer be accepted and is eligible for deletion.
	ExpiresAt string `json:"expiresAt"`

	// ExpiresAtTimestamp represents Unix, seconds since the epoch. Still UTC.
	// After this time the code will no longer be accepted and is eligible for deletion.
	ExpiresAtTimestamp int64 `json:"expiresAtTimestamp"`

	// LongExpiresAt and LongExpiresAtTimestamp repesents the time when the long
	// code expires, in UTC seconds since epoch.
	LongExpiresAt          string `json:"longExpiresAt,omitempty"`
	LongExpiresAtTimestamp int64  `json:"longExpiresAtTimestamp,omitempty"`

	Error     string `json:"error"`
	ErrorCode string `json:"errorCode,omitempty"`
}

IssueCodeResponse defines the response type for IssueCodeRequest.

type VerificationCertificateRequest

type VerificationCertificateRequest struct {
	VerificationToken string `json:"token"`
	ExposureKeyHMAC   string `json:"ekeyhmac"`
}

VerificationCertificateRequest is used to accept a long term token and an HMAC of the TEKs. The details of the HMAC calculation are available at: https://github.com/google/exposure-notifications-server/blob/main/docs/design/verification_protocol.md

Requires API key in a HTTP header, X-API-Key: APIKEY

type VerificationCertificateResponse

type VerificationCertificateResponse struct {
	Certificate string `json:"certificate,omitempty"`
	Error       string `json:"error,omitempty"`
	ErrorCode   string `json:"errorCode,omitempty"`
}

VerificationCertificateResponse either contains an error or contains a signed certificate that can be presented to the configured exposure notifications server to publish keys along w/ the certified diagnosis.

type VerifyCodeRequest

type VerifyCodeRequest struct {
	VerificationCode string   `json:"code"`
	AcceptTestTypes  []string `json:"accept,omitempty"`
}

VerifyCodeRequest is the request structure for exchanging a short term Verification Code (OTP) for a long term token (a JWT) that can later be used to sign TEKs.

'code' is either the issued short code or long code issued to the user. Either one is

acceptable. Note that they normally have different expiry times.

'accept' is a list of accepted test types by the client. Acceptable values are

• ["confirmed"]
• ["confirmed", "likely"] == ["likely"]
• ["confirmed", "likely", "negative"] == ["negative"] These values form a hierarchy, if a client will accept 'likely' they must accept both confirmed and likely. 'negative' indicates you accept confirmed, likely, and negative. A client can pass in the complete list they accept or the "highest" value they can accept. If this value is omitted or is empty, the client agrees to accept ALL possible test types, including test types that may be introduced in the future.

Requires API key in a HTTP header, X-API-Key: APIKEY

func (*VerifyCodeRequest) GetAcceptedTestTypes

func (v *VerifyCodeRequest) GetAcceptedTestTypes() (AcceptTypes, error)

GetAcceptedTestTypes validates the AcceptedTestTypes of a VerifyCodeRequest and upconverts the list into a set (map) of the effective accepted test types. If an invalid test type is in the API request, an error is returned.

type VerifyCodeResponse

type VerifyCodeResponse struct {
	TestType          string `json:"testtype,omitempty"`
	SymptomDate       string `json:"symptomDate,omitempty"` // ISO 8601 formatted date, YYYY-MM-DD
	VerificationToken string `json:"token,omitempty"`       // JWT - signed, not encrypted.
	Error             string `json:"error,omitempty"`
	ErrorCode         string `json:"errorCode,omitempty"`
}

VerifyCodeResponse either contains an error, or contains the test parameters (type and [optional] date) as well as the verification token. The verification token may be sent back on a valid VerificationCertificateRequest later.