api

package
v0.33.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 21, 2021 License: Apache-2.0 Imports: 6 Imported by: 0

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

View Source 
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"
	// TestTypeUserReport is the string that represents a user initiated report.
	TestTypeUserReport = "user-report"

	// ErrUnparsableRequest indicates that the request could not be correctly parsed.
	ErrUnparsableRequest = "unparsable_request"
	// ErrInternal indicates some server-side error whose details are opaque to the caller.
	// this could mean a database or RPC connection drop or some other internal outage.
	ErrInternal = "internal_server_error"

	// 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 this 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"
	// ErrMissingDate indicates the realm requires a date, but none was supplied.
	ErrMissingDate = "missing_date"
	// ErrInvalidDate indicates the realm requires a date, but the supplied date
	// was older or newer than the allowed date range.
	ErrInvalidDate = "invalid_date"
	// ErrUUIDAlreadyExists indicates that the UUID has already been used for an issued code.
	ErrUUIDAlreadyExists = "uuid_already_exists"
	// ErrMaintenanceMode indicates that the server is read-only for maintenance.
	ErrMaintenanceMode = "maintenance_mode"
	// ErrQuotaExceeded indicates the realm has exceeded its daily allotment of codes.
	ErrQuotaExceeded = "quota_exceeded"
	// ErrSMSQueueFull indicates that Twilio's SMS queue is full and may not accept more SMS messages to send.
	ErrSMSQueueFull = "sms_queue_full"
	// ErrPhoneNumberInvalid indicates the phone number could not be parsed, details in the error message.
	ErrPhoneNumberInvalid = "phone_number_invalid"
	// ErrSMSFailure indicates that Twilio's responded with a failure.
	ErrSMSFailure = "sms_failure"
	// ErrMissingNonce indicates a UserReport request is missing the nonce value.
	ErrMissingNonce = "missing_nonce"
	// ErrMissingPhone indicates a UserReport request is missing the phone number.
	ErrMissingPhone = "missing_phone"

	// User report specific responses
	// ErrUserReportTryLater indicates that user report is not allowed right now, which could be for several
	// reasons: phone number already used, PHA hit self report quota, PHA disabled self report.
	ErrUserReportTryLater = "user_report_try_later"

	// 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"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type AcceptTypes added in v0.4.0 

type AcceptTypes map[string]struct{}

AcceptTypes is a map of string to struct.

func (AcceptTypes) AddAcceptTypes added in v0.4.0 

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

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

type AndroidDataResponse added in v0.20.0 

type AndroidDataResponse struct {
	Relation []string      `json:"relation,omitempty"`
	Target   AndroidTarget `json:"target,omitempty"`
}

AndroidDataResponse is the structure returned from Android assetlinks.

type AndroidTarget added in v0.20.0 

type AndroidTarget struct {
	Namespace    string   `json:"namespace,omitempty"`
	PackageName  string   `json:"package_name,omitempty"`
	Fingerprints []string `json:"sha256_cert_fingerprints,omitempty"`
}

type BatchIssueCodeRequest added in v0.18.0 

type BatchIssueCodeRequest struct {
	Padding Padding             `json:"padding"`
	Codes   []*IssueCodeRequest `json:"codes"`
}

BatchIssueCodeRequest defines the request for issuing many codes at once.

type BatchIssueCodeResponse added in v0.18.0 

type BatchIssueCodeResponse struct {
	Padding Padding              `json:"padding"`
	Codes   []*IssueCodeResponse `json:"codes,omitempty"`

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

BatchIssueCodeResponse defines the response for BatchIssueCodeRequest.

type BatchUser added in v0.9.0 

type BatchUser struct {
	Email string `json:"email"`
	Name  string `json:"name"`
}

BatchUser represents a single user's email/name.

type CheckCodeStatusRequest added in v0.4.0 

type CheckCodeStatusRequest struct {
	Padding Padding `json:"padding"`

	// 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 added in v0.4.0 

type CheckCodeStatusResponse struct {
	Padding Padding `json:"padding"`

	// 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"`

	// ErrorCodeLegacy exists to populate the JSON with a deprecated error_code
	// key. This will be removed in a future version. Consumers should use
	// `errorCode` instead.
	ErrorCodeLegacy string `json:"error_code"`
}

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 added in v0.3.0 

func InternalError() *ErrorReturn

InternalError constructs a generic internal error.

func (*ErrorReturn) WithCode added in v0.3.0 

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

WithCode adds an error code to an ErrorReturn

type ExpireCodeRequest added in v0.5.1 

type ExpireCodeRequest struct {
	Padding Padding `json:"padding"`

	// 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 added in v0.5.1 

type ExpireCodeResponse struct {
	Padding Padding `json:"padding"`

	// 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 represents 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 IOSAppLinks struct {
	Apps    []string    `json:"apps"`
	Details []IOSDetail `json:"details,omitempty"`
}

type IOSAppstrings added in v0.20.0 

type IOSAppstrings struct {
	Apps []string `json:"apps,omitempty"`
}

type IOSDataResponse added in v0.20.0 

type IOSDataResponse struct {
	Applinks IOSAppLinks `json:"applinks"`

	// The following two fields are included for completeness' sake, but are not
	// currently populated/used by the system.
	Webcredentials *IOSAppstrings `json:"webcredentials,omitempty"`
	Appclips       *IOSAppstrings `json:"appclips,omitempty"`
}

IOSDataResponse is the iOS format is specified by: 

https://developer.apple.com/documentation/safariservices/supporting_associated_domains

type IOSDetail added in v0.20.0 

type IOSDetail struct {
	AppID string   `json:"appID,omitempty"`
	Paths []string `json:"paths,omitempty"`
}

type IssueCodeRequest 

type IssueCodeRequest struct {
	Padding Padding `json:"padding"`

	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         float32 `json:"tzOffset"`
	Phone            string  `json:"phone"`
	SMSTemplateLabel string  `json:"smsTemplateLabel"`

	// Optional: UUID is a handle which allows the issuer to track status
	// of the issued verification code. If omitted the server will generate the UUID.
	UUID string `json:"uuid"`

	// ExternalIssuerID is optional information supplied by the API caller to
	// uniquely identify the entity making this request. This is useful where
	// callers are using a single API key behind an ERP, or when callers are using
	// the verification server as an API with a different authentication system.
	// This field is optional.
	//
	// The information provided is stored exactly as-is. If the identifier is
	// uniquely identifying PII (such as an email address, employee ID, SSN, etc),
	// the caller should apply a cryptographic hash before sending that data. The
	// system does not sanitize or encrypt these external IDs, it is the caller's
	// responsibility to do so.
	ExternalIssuerID string `json:"externalIssuerID"`

	// OnlyGenerateSMS is a boolean field which indicates whether the response
	// should generate and return the SMS message.
	//
	// If true, the system will not send the SMS message, but the message will be
	// returned in the response.
	//
	// If true, the Phone field must also be provided.
	//
	// If true and the realm has Authenticated SMS enabled, the returned message
	// will include the authentication signature as part of the body.
	//
	// This field can only be set to true if the realm is configured to allow
	// generated SMS messages.
	OnlyGenerateSMS bool `json:"onlyGenerateSMS"`
}

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 {
	Padding Padding `json:"padding"`

	// 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 represents the time when the long
	// code expires, in UTC seconds since epoch.
	LongExpiresAt          string `json:"longExpiresAt,omitempty"`
	LongExpiresAtTimestamp int64  `json:"longExpiresAtTimestamp,omitempty"`

	// GenerateSMS is the compiled SMS message. This field will only be present if
	// a phone number was provided and onlyGenerateSMS was specified on the
	// request.
	GeneratedSMS string `json:"generatedSMS,omitempty"`

	// Phone is the E.164-formatted phone number in which to send the compiled SMS
	// message. This field will only be present if a phone number was provided and
	// onlyGenerateSMS was specified on the request.
	Phone string `json:"phone,omitempty"`

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

IssueCodeResponse defines the response type for IssueCodeRequest.

type Padding added in v0.7.0 

type Padding []byte

Padding is an optional field to change the size of the request or response. It's arbitrary bytes that should be ignored or discarded. It primarily exists to prevent a network observer from building a model based on request or response sizes.

func (Padding) MarshalJSON added in v0.7.0 

func (p Padding) MarshalJSON() ([]byte, error)

MarshalJSON is a custom JSON marshaler for padding. It generates and returns 1-2kb (random) of base64-encoded bytes.

func (*Padding) UnmarshalJSON added in v0.19.2 

func (p *Padding) UnmarshalJSON(b []byte) error

UnmarshalJSON is a custom JSON unmarshaler for padding. The field is meaningless bytes, so this is just a passthrough.

type UserBatchRequest added in v0.9.0 

type UserBatchRequest struct {
	Users       []BatchUser `json:"users"`
	SendInvites bool        `json:"sendInvites"`
}

UserBatchRequest is a request for bulk creation of users. This is called by the Web frontend. API is served at /users/import/userbatch

type UserBatchResponse added in v0.9.0 

type UserBatchResponse struct {
	NewUsers []*BatchUser `json:"newUsers"`

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

UserBatchResponse defines the response type for UserBatchRequest.

type UserReportRequest added in v0.25.0 

type UserReportRequest struct {
	Padding Padding `json:"padding"`

	SymptomDate string `json:"symptomDate"` // ISO 8601 formatted date, YYYY-MM-DD
	TestDate    string `json:"testDate"`
	// TZOffset 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 float32 `json:"tzOffset"`
	// Phone is required in this API. The verification code will be delivered over SMS.
	Phone string `json:"phone"`

	// Nonce must be 256 bytes of random data, base64 encoded.
	Nonce string `json:"nonce"`
}

UserReportRequest defines the structure for a user initiated report. This is a device API hosted on the apiserver.

Support level: ALPHA This API is not guaranteed to be backwards compatible until such time it is moved to beta.

Inclusion of the test date is required, inclusion of the symptom date is optional.

A phone number is required. The verification code is only presented over SMS.

The nonce field must be a 256 random bytes, base64 encoded. This nonce field must be passed back on the VerifyCodeRequest request later.

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

type UserReportResponse added in v0.25.0 

type UserReportResponse struct {
	Padding Padding `json:"padding"`

	// 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"`

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

UserReportResponse is the reply from a UserReportRequest.

type VerificationCertificateRequest 

type VerificationCertificateRequest struct {
	Padding Padding `json:"padding"`

	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 {
	Padding Padding `json:"padding"`

	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 {
	Padding Padding `json:"padding"`

	VerificationCode string   `json:"code"`
	AcceptTestTypes  []string `json:"accept"`

	// Optional: If present must be the same nonce that was used to request the verification code.
	// base64 encoded.
	Nonce string `json:"nonce,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.

The special type of test, '"user-report"' can be added safely to any of the other types.

The nonce must be provided when validating a self report key.

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

func (*VerifyCodeRequest) GetAcceptedTestTypes added in v0.4.0 

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 {
	Padding Padding `json:"padding"`

	TestType          string `json:"testtype,omitempty"`
	SymptomDate       string `json:"symptomDate,omitempty"` // ISO 8601 formatted date, YYYY-MM-DD
	TestDate          string `json:"testDate,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.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.