ticket

type Approver struct {
	ID      string `json:"id"`
	Display string `json:"display"`
}

type Change struct {
	Input string `json:"input"`
	// Change is ChangeChanged, ChangeNew or ChangeGone.
	Change string `json:"change"`
}

type Context string

type Decision struct {
	V        int     `json:"v"`
	Ticket   string  `json:"ticket"`
	Instance string  `json:"instance"`
	KeyID    string  `json:"key_id"` // the lock's key
	PlanHash string  `json:"plan_hash"`
	Decision Outcome `json:"decision"`
	// Reason is the human's reason (a denial's, mostly); untrusted.
	Reason   string   `json:"reason"`
	Approver Approver `json:"approver"`
	// Facade is the facade the human answered on ("tty", "deck", ...).
	Facade string    `json:"facade"`
	At     time.Time `json:"at"`
	// Nonce is single use: a lock consumes it with the decision.
	Nonce    string `json:"nonce"`
	HubKeyID string `json:"hub_key_id"` // KeyID of the hub's key
	// Device is the assertion of the device the human decided on (facade
	// FacadeMobile), over Statement; absent from any other facade. A lock
	// checks it with VerifyDevice against the devices it pins.
	Device *DeviceAssertion `json:"device,omitempty"`
	// Rule is what decided a VersionKinds decision (required there,
	// absent from a Version one), for the lock's audit.
	Rule *Rule `json:"rule,omitempty"`
	// Secret, on an approval of a connect ticket that asked for one
	// (Subject.SecretTo), is the backend's secret sealed to the lock
	// (SealSecret, OpenSecret): the hub relays it without reading it.
	Secret *Sealed `json:"secret,omitempty"`
	Sig    string  `json:"sig,omitempty"`
}

type Device struct {
	V int `json:"v"`
	// ID is DeviceID(credential): "webauthn:" and 16 bytes of hex.
	ID string `json:"id"`
	// Credential is the WebAuthn credential id (base64url).
	Credential string `json:"credential"`
	// Name is the human's label ("phone"), for display.
	Name string `json:"name"`
	// RPID is the WebAuthn relying party id (the facade's host name) and
	// Origin the facade's origin ("https://hub.example.net").
	RPID   string `json:"rp_id"`
	Origin string `json:"origin"`
	// ES256 is the credential's P-256 public key, uncompressed (65 bytes,
	// base64url).
	ES256 string `json:"es256"`
	// X25519 is the device's sealing key (32 bytes, base64url).
	X25519 string `json:"x25519"`
}

type DeviceAssertion struct {
	Device     string `json:"device"` // Device.ID
	AuthData   string `json:"auth_data"`
	ClientData string `json:"client_data"`
	Sig        string `json:"sig"`
}

type DeviceBox struct {
	Device string `json:"device"`
	Box    Sealed `json:"box"`
}

type DeviceSet struct {
	V       int      `json:"v"`
	Devices []Device `json:"devices"`
}

type DeviceStatement struct {
	V        int       `json:"v"`
	Ticket   string    `json:"ticket"`
	Instance string    `json:"instance"`
	KeyID    string    `json:"key_id"`
	PlanHash string    `json:"plan_hash"`
	Decision Outcome   `json:"decision"`
	Reason   string    `json:"reason"`
	Approver string    `json:"approver"`
	Display  string    `json:"display"`
	Facade   string    `json:"facade"`
	At       time.Time `json:"at"`
	Nonce    string    `json:"nonce"`
	HubKeyID string    `json:"hub_key_id"`
	Device   string    `json:"device"`
	// TicketHash is TicketHash of the signed ticket, as the lock sent it.
	TicketHash string `json:"ticket_hash"`
}

type FacadeKey struct {
	Facade string `json:"facade"`
	// Key is the raw 32-byte public key, standard base64.
	Key string `json:"key"`
}

type FacadeSet struct {
	V       int         `json:"v"`
	Facades []FacadeKey `json:"facades"`
}

type Flags struct {
	// Production: the target is production; the facade asks for the
	// typed instance name.
	Production bool `json:"production"`
	// NeverAuto: never approved by an auto mode. Always set on a
	// RiskGrant ticket (Validate refuses one without it).
	NeverAuto bool `json:"never_auto"`
	// Retype, when set, is the answer that asks the lock to retype values.
	Retype string `json:"retype"`
}

type HubRequest struct {
	V        int         `json:"v"`
	ID       string      `json:"id"` // NewID, made by the hub
	Kind     RequestKind `json:"kind"`
	Ticket   string      `json:"ticket"`
	Instance string      `json:"instance"`
	KeyID    string      `json:"key_id"` // the lock's key
	Approver Approver    `json:"approver"`
	Facade   string      `json:"facade"`
	At       time.Time   `json:"at"`
	// Reveal is the facade's key, for RequestReveal only.
	Reveal   *RevealKey `json:"reveal,omitempty"`
	HubKeyID string     `json:"hub_key_id"`
	Sig      string     `json:"sig,omitempty"`
}

type KeyCert struct {
	V      int    `json:"v"`
	KeyID  string `json:"key_id"` // the signing Ed25519 key
	X25519 string `json:"x25519"`
	// Bind ties the key to one use ("" for a long-lived key).
	Bind string `json:"bind"`
	Sig  string `json:"sig,omitempty"`
}

type Kind string

type Outcome string

type PII struct {
	// Touched names the kinds of personal data involved ("email").
	Touched []string `json:"touched"`
	// ClearSealed is the unmasked screen sealed to one facade's device
	// key, for a facade able to show it; nil otherwise.
	ClearSealed *Sealed `json:"clear_sealed"`
	// SealedFor is the clear screen sealed to each device the lock pins
	// (SealClearScreen), when the lock is set to seal it; absent
	// otherwise. ClearSealed (one recipient, any facade key) is not used
	// for devices.
	SealedFor []DeviceBox `json:"sealed_for,omitempty"`
}

type PinnedFacade struct {
	Facade string
	Key    ed25519.PublicKey
}

type Renewal struct {
	// Of is the expired ticket.
	Of string `json:"of"`
	// Reason is why Of ended: RenewExpired or RenewApprovalExpired.
	Reason string `json:"reason"`
	// ApprovedAt is when Of was approved, for RenewApprovalExpired.
	ApprovedAt *time.Time `json:"approved_at"`
	// Checked: the lock compared the plan-hash inputs. False, Changes is
	// empty because the lock could not compare them (the run still checks
	// the plan hash, and refuses a stale plan).
	Checked bool `json:"checked"`
	// Changes are the inputs whose digest moved, by name.
	Changes []Change `json:"changes"`
}

type RequestKind string

type Requester struct {
	Agent   string `json:"agent"`
	Session string `json:"session"`
}

type RevealAnswer struct {
	V        int     `json:"v"`
	Request  string  `json:"request"` // HubRequest.ID
	Reveal   string  `json:"reveal"`  // RevealKey.ID
	Ticket   string  `json:"ticket"`
	Instance string  `json:"instance"`
	KeyID    string  `json:"key_id"` // the lock's key
	Box      *Sealed `json:"box"`
	Sig      string  `json:"sig,omitempty"`
}

type RevealKey struct {
	V int `json:"v"`
	// ID names this reveal (NewID); the box is bound to it.
	ID       string `json:"id"`
	Ticket   string `json:"ticket"`
	Instance string `json:"instance"`
	KeyID    string `json:"key_id"` // the lock's key
	Facade   string `json:"facade"`
	// EPK is the ephemeral X25519 public key.
	EPK         string    `json:"epk"`
	At          time.Time `json:"at"`
	FacadeKeyID string    `json:"facade_key_id"`
	Sig         string    `json:"sig,omitempty"`
}

type Risk string

type Rule struct {
	By string `json:"by"`
	ID string `json:"id,omitempty"`
}

type Screen struct {
	// Header names the request ("db / shop · tier read").
	Header string `json:"header"`
	// Note is the agent's one-line reason (untrusted).
	Note string `json:"note"`
	// Body are the lines of the request; Warnings are shown in red.
	Body     []string `json:"body"`
	Warnings []string `json:"warnings"`
	// Red frames the screen in red outside production too.
	Red bool `json:"red"`
}

type Sealed struct {
	Alg   string `json:"alg"`
	EPK   string `json:"epk"`   // ephemeral X25519 public key
	Nonce string `json:"nonce"` // 24 bytes
	CT    string `json:"ct"`    // ciphertext and tag
}

type Source struct {
	// Lock is the product: "locksql", "lockfile", ...
	Lock string `json:"lock"`
	// Instance names the lock instance ("crm-prod"); decisions are bound
	// to it.
	Instance string `json:"instance"`
	// KeyID is KeyID of the Ed25519 key that signs the ticket.
	KeyID string `json:"key_id"`
}

type Subject struct {
	// Profile is the lock profile the request runs under.
	Profile string `json:"profile,omitempty"`
	// Endpoint is the backend (connect: "db.internal:5432/shop") or the
	// new host (endpoint: "api.example.com"): host[:port][/path] only,
	// without userinfo, query, options or whitespace (validEndpoint).
	Endpoint string `json:"endpoint,omitempty"`
	// Credential is where the lock gets the secret (connect only): one of
	// the Credential* sources.
	Credential string `json:"credential,omitempty"`
	// SecretTo, on a connect ticket, asks the decider for the secret: it
	// is the lock's one-use X25519 public key (32 bytes, base64url) for
	// this ticket, signed with the ticket. The decision carries the
	// secret sealed to it (Decision.Secret): the hub relays a box it
	// cannot open. Set when the profile is "ask", or its Vault token has
	// expired.
	SecretTo string `json:"secret_to,omitempty"`
	// Verb is an action's verb ("publish", "purge", "GET") or an
	// endpoint's method.
	Verb string `json:"verb,omitempty"`
	// Target is what the verb acts on (a queue, a path, a route, a table),
	// without query string, fragment or whitespace (validTarget).
	Target string `json:"target,omitempty"`
}

type Ticket struct {
	V         int       `json:"v"`
	ID        string    `json:"id"` // NewID
	Source    Source    `json:"source"`
	Workspace string    `json:"workspace"`
	Requester Requester `json:"requester"`
	Risk      Risk      `json:"risk"`
	Flags     Flags     `json:"flags"`
	Screen    Screen    `json:"screen"`
	PII       PII       `json:"pii"`
	// PlanHash binds the ticket to the plan it asks for (HashOf).
	PlanHash string `json:"plan_hash"`
	// PolicyFP is the fingerprint of the policy the plan was made under.
	PolicyFP string    `json:"policy_fp"`
	Created  time.Time `json:"created"`
	// Expires is when a pending ticket expires; nil never.
	Expires *time.Time `json:"expires"`
	// Renews, when set, makes this ticket the renewal of an expired one
	// (Renewal); absent otherwise.
	Renews *Renewal `json:"renews,omitempty"`
	// Kind is what a VersionKinds ticket asks for, and Subject its
	// structured request; a Version ticket has neither.
	Kind    Kind     `json:"kind,omitempty"`
	Subject *Subject `json:"subject,omitempty"`
	Sig     string   `json:"sig,omitempty"`
}