port

type AgentStore interface {
	// Save inserts or updates an AgentRegistration. If agent.ID == 0 the
	// implementation must assign a new ID and set it on the aggregate.
	Save(ctx context.Context, agent *domain.AgentRegistration) error

	// FindByID returns the agent with the given database ID or
	// domain.ErrNotFound.
	FindByID(ctx context.Context, id int64) (*domain.AgentRegistration, error)

	// FindByAgentID returns the agent with the given stable agent UUID.
	FindByAgentID(ctx context.Context, agentID string) (*domain.AgentRegistration, error)

	// FindByAnsName returns the agent with the given versioned ANS name.
	FindByAnsName(ctx context.Context, ansName domain.AnsName) (*domain.AgentRegistration, error)

	// ExistsByAnsName returns true if any registration uses the given name.
	ExistsByAnsName(ctx context.Context, ansName domain.AnsName) (bool, error)

	// FindAllByAgentHost returns every registration (any version, any status)
	// for the given FQDN, newest first.
	FindAllByAgentHost(ctx context.Context, host string) ([]*domain.AgentRegistration, error)

	// FindExistingByFQDN returns ACTIVE or PENDING_* registrations for the
	// given FQDN, newest first. Used to check for supersession candidates.
	FindExistingByFQDN(ctx context.Context, fqdn string) ([]*domain.AgentRegistration, error)

	// ListByOwner returns a cursor page of agents owned by ownerID.
	ListByOwner(
		ctx context.Context,
		ownerID string,
		filter ListFilter,
	) (*CursorPage[*domain.AgentRegistration], error)

	// ExpireLapsedPendingValidation atomically transitions to EXPIRED
	// every registration that is still PENDING_VALIDATION with a
	// PENDING certificate order whose challenge window lapsed at or
	// before now, returning the number transitioned. The agent-expiry
	// sweeper uses it to honor the spec's "PENDING_VALIDATION
	// registrations are not cancellable and will auto-expire".
	//
	// The transition is a single guarded write — not a read-then-save
	// — so a verify-acme that advances the same row (to PENDING_DNS,
	// or to a non-PENDING order state) between scans cannot be
	// clobbered: such a row simply no longer matches. In-flight
	// (order ISSUING) and terminally-failed (order FAILED)
	// registrations are excluded; they leave PENDING_VALIDATION
	// through the cancel route instead, per domain.Cancel's
	// eligibility rule.
	ExpireLapsedPendingValidation(ctx context.Context, now time.Time) (int64, error)

	// Delete removes the registration with the given ID. Used only for
	// administrative cleanup; normal lifecycle uses Revoke.
	Delete(ctx context.Context, id int64) error
}

type AuthProvider interface {
	// Authenticate extracts and validates credentials from the request,
	// returning the authenticated Identity on success. An error is returned
	// if credentials are missing, malformed, or invalid.
	Authenticate(ctx context.Context, r *http.Request) (*Identity, error)

	// Middleware returns an HTTP middleware that authenticates every
	// incoming request and stores the Identity in the request context.
	// On authentication failure the middleware must return 401.
	Middleware() func(http.Handler) http.Handler
}

type ByocCertificateStore interface {
	Save(ctx context.Context, agentID string, cert *domain.ByocServerCertificate) error
	FindByAgentID(ctx context.Context, agentID string) ([]*domain.ByocServerCertificate, error)
	FindLatestValidByAgentID(ctx context.Context, agentID string) (*domain.ByocServerCertificate, error)
}

type CertificateStore interface {
	// SaveIdentityCertificate persists a newly issued identity certificate.
	SaveIdentityCertificate(
		ctx context.Context,
		agentID string,
		cert *domain.StoredCertificate,
	) error

	// FindIdentityCertificatesByAgent returns all identity certificates
	// for the given agent, newest first.
	FindIdentityCertificatesByAgent(
		ctx context.Context,
		agentID string,
	) ([]*domain.StoredCertificate, error)

	// UpdateCertificateStatus updates the status of an existing certificate.
	UpdateCertificateStatus(
		ctx context.Context,
		cert *domain.StoredCertificate,
	) error

	// SaveCSR persists a new or updated CSR (identity or server).
	// Upserts on csr_id; status transitions replace the previous row.
	SaveCSR(
		ctx context.Context,
		agentID string,
		csr *domain.AgentCSR,
	) error

	// FindCSRByID returns the CSR with the given ID, scoped to the
	// given agent. Used by the CSR-status handler and the registration
	// flow's post-rotation refresh.
	FindCSRByID(
		ctx context.Context,
		agentID, csrID string,
	) (*domain.AgentCSR, error)

	// FindLatestPendingCSRByType returns the most recent PENDING CSR
	// of the given type (IDENTITY or SERVER) for an agent, or
	// (nil, nil) when none exists. Used by VerifyACME to pull the
	// CSRs submitted at register time for signing once domain
	// control has been proven.
	FindLatestPendingCSRByType(
		ctx context.Context,
		agentID string,
		csrType domain.CSRType,
	) (*domain.AgentCSR, error)
}

type CertificateValidator interface {
	// ValidateServerCertificate verifies a BYOC server certificate against
	// the expected FQDN. It checks PEM parsing, chain validity, CN/SAN
	// matching, validity period, signature algorithm, and key strength.
	ValidateServerCertificate(
		ctx context.Context,
		leafPEM, chainPEM, expectedFQDN string,
	) (*ValidatedCert, error)

	// ValidateIdentityCSR verifies an identity CSR before it is signed.
	// It checks PEM parsing, signature, key strength, and that the URI SAN
	// matches the expected ANS name.
	ValidateIdentityCSR(
		ctx context.Context,
		csrPEM string,
		expectedAnsName string,
	) error

	// ValidateServerCSR verifies a server CSR before issuance. Server
	// CSRs must carry the agent's FQDN as a DNS SAN (TLS server-auth
	// convention). Falls back to matching against the CSR subject CN
	// for SDK-compat when no SAN is present.
	ValidateServerCSR(
		ctx context.Context,
		csrPEM string,
		expectedFQDN string,
	) error
}

type CursorPage[T any] struct {
	Items         []T
	NextCursor    string
	HasMore       bool
	ReturnedCount int
}

type DIDDocument struct {
	ID              string
	AssertionMethod []VerificationMethod
}

type DIDResolver interface {
	// Resolve returns the DID document for the given canonical
	// did:web identifier. Implementations return domain errors with
	// the DID_* codes (DID_RESOLUTION_FAILED,
	// DID_DOCUMENT_ID_MISMATCH, DID_REDIRECT_DOMAIN_MISMATCH).
	Resolve(ctx context.Context, did string, hints []KeyHint) (*DIDDocument, error)
}

type DNSVerifier interface {
	// VerifyRecords performs DNS lookups for each expected record and
	// returns a per-record report plus an overall pass/fail summary.
	// A VerificationResult is always returned even on partial failures;
	// a non-nil error indicates a systemic failure (e.g., DNS unreachable).
	VerifyRecords(
		ctx context.Context,
		fqdn string,
		expected []domain.ExpectedDNSRecord,
	) (*VerificationResult, error)
}

type EndpointStore interface {
	Save(ctx context.Context, endpoints *domain.AgentEndpoints) error
	FindByAgentID(ctx context.Context, agentID string) (*domain.AgentEndpoints, error)
	FindByAgentIDs(ctx context.Context, agentIDs []string) (map[string]*domain.AgentEndpoints, error)
}

type EventBus interface {
	// Publish delivers the event to all handlers registered for its type.
	// Returns an error only if the bus itself is broken (e.g., shut down);
	// per-handler errors are surfaced through the adapter's logging.
	Publish(ctx context.Context, event domain.Event) error

	// Subscribe registers a handler for a specific event type.
	// Subscriptions made after Close are rejected.
	Subscribe(eventType domain.EventType, handler EventHandler) error
}

type EventHandler func(ctx context.Context, event domain.Event) error

type FinalizeOrderRequest struct {
	// OrderRef is the provider-opaque handle returned by CreateOrder
	// (an ACME order URL, an internal id, …).
	OrderRef string
	// CSRPEM is the operator-submitted server CSR. Per RFC 8555 the
	// CSR is presented at finalize time, not at order creation.
	CSRPEM string
	// FQDN is the agent host the certificate must cover.
	FQDN string
	// Verified lists the challenge types whose artifacts the RA's own
	// pre-flight check found published. ACME implementations MUST only
	// answer a verified challenge: telling the provider to validate an
	// unsatisfied challenge invalidates the authorization — and with it
	// the whole order. Self-signed implementations may ignore it (the
	// RA's gate is authoritative there).
	Verified []domain.ChallengeType
}

type HTTPChallengeVerifier interface {
	// VerifyHTTPChallenge fetches `http://<fqdn><path>` and reports
	// whether the response body matches the expected content (the key
	// authorization for account-bound challenges, the raw token
	// otherwise). Returns (false, nil) when the artifact is missing or
	// mismatched; a non-nil error indicates a systemic failure that
	// prevented checking at all (which callers treat the same as
	// not-published, since an unreachable host cannot prove control).
	VerifyHTTPChallenge(ctx context.Context, fqdn, path, expectedContent string) (bool, error)
}

type Identity struct {
	// Subject uniquely identifies the authenticated principal
	// (e.g., an OIDC "sub" claim, a user ID, or an API key owner).
	Subject string

	// Scopes lists the permissions granted to this identity.
	Scopes []string

	// IsAdmin is true if this identity has administrative privileges.
	IsAdmin bool
}

type IdentityCertificateAuthority interface {
	// IssueIdentityCertificate signs the given identity CSR and returns
	// the resulting certificate plus chain.
	IssueIdentityCertificate(
		ctx context.Context,
		csrPEM string,
		ansName string,
	) (*IssuedCert, error)

	// RevokeCertificate revokes a previously issued certificate at the
	// CA, so private CRL/OCSP distribution reflects the revocation —
	// the RA's own database flip and transparency-log emit are the
	// caller's responsibility. Must be idempotent (see
	// RevokeCertificateRequest).
	RevokeCertificate(
		ctx context.Context,
		req RevokeCertificateRequest,
	) error

	// GetCACertificate returns the CA's root certificate PEM.
	// Clients use this to build trust chains.
	GetCACertificate(ctx context.Context) (string, error)
}

type IdentityLinkStore interface {
	// Link upserts a live link for the pair. Returns true when a new
	// link was created, false when the pair was already live
	// (idempotent — an already-linked agent in a batch is not an
	// error, and is excluded from the sealed batch event).
	Link(ctx context.Context, identityID, agentID string, now time.Time) (bool, error)

	// Unlink flips the live link to UNLINKED. Not-found error when no
	// live link exists.
	Unlink(ctx context.Context, identityID, agentID string, now time.Time) error

	// ListLiveByIdentity returns the identity's live links.
	ListLiveByIdentity(ctx context.Context, identityID string) ([]*domain.IdentityLink, error)

	// ListLiveByAgent returns the agent's live links.
	ListLiveByAgent(ctx context.Context, agentID string) ([]*domain.IdentityLink, error)
}

type IdentityStore interface {
	// Save upserts the aggregate. The storage layer enforces the two
	// uniqueness rules with partial indexes: one live (non-REVOKED)
	// row per (provider, kind, value), and one VERIFIED row per
	// (kind, value) across all owners — first to prove wins; a save
	// that loses the race maps to a conflict error.
	Save(ctx context.Context, identity *domain.VerifiedIdentity) error

	// FindByID returns the identity with the given identityId.
	FindByID(ctx context.Context, identityID string) (*domain.VerifiedIdentity, error)

	// FindLive returns the owner's non-REVOKED row for (kind, value),
	// or a not-found error. Drives the idempotent re-add: a re-POST
	// of the same value while PENDING_CONTROL returns the same
	// identity with a fresh challenge.
	FindLive(ctx context.Context, providerID string, kind domain.IdentifierKind, value string) (*domain.VerifiedIdentity, error)

	// ExistsVerified reports whether ANY owner holds a VERIFIED row
	// for (kind, value) — early duplicate feedback at register time.
	// The authoritative guard is the proven-uniqueness index at
	// verify time.
	ExistsVerified(ctx context.Context, kind domain.IdentifierKind, value string) (bool, error)

	// ListByOwner returns the principal's identities, newest first,
	// cursor-paginated with the same opaque-cursor convention as the
	// agent list (§5.6.1 pagination inherits, never invents).
	ListByOwner(ctx context.Context, providerID string, limit int, cursor string) (*CursorPage[*domain.VerifiedIdentity], error)

	// ConsumeChallenge atomically consumes the live challenge nonce:
	// a conditional update that succeeds only while the stored nonce
	// matches, is unconsumed, and is unexpired. Exactly one of two
	// concurrent verify-control calls can win (the TOCTOU guard);
	// the loser receives an invalid-state error. MUST be called
	// inside the verify-control success transaction.
	ConsumeChallenge(ctx context.Context, identityID, nonce string, now time.Time) error

	// ClaimChallenge takes the short-TTL provisional claim on the
	// live nonce before the seal-before-success TL round trip
	// (design §5.6.1): a conditional update that succeeds only while
	// the nonce matches, is unconsumed, and is not already claimed
	// by an attempt fresher than staleBefore. Serializes concurrent
	// verify-control attempts so at most one can seal; the loser
	// gets an invalid-state error. A claim is NOT consumption.
	ClaimChallenge(ctx context.Context, identityID, nonce string, now, staleBefore time.Time) error

	// ReleaseChallenge releases a provisional claim after a failed
	// attempt so the registrant can retry until the nonce expires
	// (§3.2 failed-attempts-don't-consume). Best-effort: releasing
	// an already-consumed or superseded nonce is a no-op.
	ReleaseChallenge(ctx context.Context, identityID, nonce string) error

	// StageChallenge persists a freshly issued challenge (and any
	// staged pending_value) onto an EXISTING row, conditionally on
	// the status and nonce observed at load time and on no live seal
	// claim — the optimistic-concurrency guard that stops a re-add /
	// rotate from clobbering a concurrently committed verify or
	// revoke (their commits race the resolver fetch between load and
	// persist). Never writes status, value, or verified_at: issuing
	// a challenge is not a state transition. A failed condition maps
	// to a precise conflict error.
	StageChallenge(ctx context.Context, identity *domain.VerifiedIdentity, expectedStatus domain.IdentityStatus, expectedNonce string, staleBefore time.Time) error

	// MarkRevoked flips a VERIFIED row to REVOKED conditionally —
	// the seal-before-success Phase C commit for Revoke. The status
	// condition (not a blind save) means a verify or rotate that
	// committed during the revoke's TL round trip is never clobbered
	// with stale column values. Zero rows → conflict.
	MarkRevoked(ctx context.Context, identityID string, now time.Time) error
}

type IssuedCert struct {
	CertPEM      string
	ChainPEM     string
	SerialNumber string
	// CertificateRef is the issuer's opaque handle for the issued
	// certificate — an ACME certificate URL, a cloud CA resource name
	// (GCP CAS) or ARN (AWS PCA), empty for the in-process self-signed
	// CAs. Persisted alongside the certificate because some providers
	// revoke by handle rather than by serial.
	CertificateRef string
	ExpiresAt      time.Time
	IssuedAt       time.Time
}

type KeyHint struct {
	Kid          string
	PublicKeyJWK json.RawMessage
}

type KeyManager interface {
	// Sign produces a signature over data using the key identified by keyID.
	// The returned signature format is adapter-defined (typically DER for
	// ECDSA, PKCS1v15 or PSS for RSA); downstream code must match the format.
	Sign(ctx context.Context, keyID string, data []byte) ([]byte, error)

	// Verify returns true if signature is valid for data under the given key.
	// A verify error (e.g., key not found) is distinct from a valid "false".
	Verify(ctx context.Context, keyID string, data, signature []byte) (bool, error)

	// GetPublicKey returns the public half of the named key. The concrete type
	// depends on the algorithm (e.g., *ecdsa.PublicKey for ECDSA_P256).
	GetPublicKey(ctx context.Context, keyID string) (crypto.PublicKey, error)

	// CreateKey generates a new key pair under the given algorithm and
	// returns its identifier. The identifier is opaque to the caller.
	CreateKey(ctx context.Context, algorithm string) (keyID string, err error)

	// ListKeys returns all known key IDs. Useful for key rotation and audit.
	ListKeys(ctx context.Context) ([]string, error)
}

type ListFilter struct {
	Statuses  []domain.RegistrationStatus // nil or empty means "all statuses"
	AgentHost string                      // exact match if non-empty
	Limit     int                         // 1-100; 0 means default (20)
	Cursor    string                      // opaque; empty for first page
}

type ProfileEmitter interface {
	// ID returns the wire-format identifier (e.g. "ANS_DNSAID", "ANS_TXT").
	// Persisted on agent rows; surfaced on the V2 register schema; used
	// as the registry key.
	ID() domain.DiscoveryProfile

	// Records returns the DNS records this profile needs an operator to
	// publish for reg. Includes both per-profile discovery records and any
	// family-level trust attestation records the profile requires (e.g.
	// _ans-badge for the ANS family, TLSA for any HTTPS-endpoint binding).
	// The service walker dedupes across profiles, so a family's shared
	// records emit once even when multiple sibling profiles request them.
	//
	// A profile that emits a transparency-log-relative trust record (the
	// ANS family's _ans-badge) is configured with the deployment TL URL
	// at construction — see ans.NewTXTProfile / ans.NewDNSAIDProfile — so this
	// stays a pure function of reg with no per-call deployment input.
	Records(reg *domain.AgentRegistration) []domain.ExpectedDNSRecord
}

type ProfileRegistry interface {
	// Get returns the profile registered under id, or (nil, false) when no
	// such profile is wired. A miss is informational, not an error: the
	// service skips unknown stored profiles (e.g. post-decommission rows)
	// and logs a WARN, rather than failing the registration.
	Get(id domain.DiscoveryProfile) (ProfileEmitter, bool)

	// IDs returns every registered profile's ID in registry-wired
	// insertion order. Order is stable across calls and process restarts
	// for a given wiring — the service walker iterates IDs() and gates
	// each by membership in reg.DiscoveryProfiles, so wiring order
	// determines emission order on the wire (TL canonical bytes).
	IDs() []domain.DiscoveryProfile
}

type RecordVerification struct {
	Record domain.ExpectedDNSRecord
	Found  bool
	// Actual carries the live answer DNS returned for this record. When
	// records exist for the name/type but none matched the expected
	// value, Actual is the first live answer (so the verify-dns 422 can
	// show the operator what is actually in their zone). When nothing
	// answered at all, Actual is empty. The service layer partitions on
	// exactly this: !Found && Actual == "" is MISSING, !Found && Actual
	// != "" is a value MISMATCH. When Found is true, Actual MAY differ
	// benignly from the expected value (e.g. an SVCB subset match where
	// the live record carries coexistence extras) and is informational
	// only — Found is the verdict.
	Actual string
	Error  string // Lookup error, if any.
	// DNSSECVerified is true when the response carried an
	// authenticated-data (AD) bit from a validating resolver. Set
	// on TLSA, SVCB, and HTTPS responses; surfaced to the TL
	// attestation so a downstream verifier can trust the cert /
	// capability / service binding without re-querying DNS. The
	// service layer enforces a hard-fail rule when AD=true and the
	// record's value disagrees with the expected one (the threat
	// shape: an attacker rewrote a record in a DNSSEC-signed zone).
	DNSSECVerified bool
}

type RenewalStore interface {
	Save(ctx context.Context, renewal *domain.ServerCertificateRenewal) error
	FindByAgentID(ctx context.Context, agentID string) (*domain.ServerCertificateRenewal, error)
	FindPendingByAgentID(ctx context.Context, agentID string) (*domain.ServerCertificateRenewal, error)
	Delete(ctx context.Context, id int64) error
	ListPendingExpired(ctx context.Context) ([]*domain.ServerCertificateRenewal, error)
}

type RevocationStore interface {
	Save(ctx context.Context, revocation *domain.AgentRevocation) error
	FindByAgentID(ctx context.Context, agentID string) (*domain.AgentRevocation, error)
}

type RevokeCertificateRequest struct {
	SerialNumber   string
	CertificateRef string
	Reason         domain.RevocationReason
}

type ServerCertificateIssuer interface {
	// CreateOrder opens an issuance order for the agent's FQDN and
	// returns the provider's domain-control challenges. The CSR is NOT
	// required yet (matching ACME, where the CSR is presented at
	// finalize). The returned order is persisted on the registration
	// or renewal aggregate.
	CreateOrder(ctx context.Context, fqdn string) (*domain.CertificateOrder, error)

	// FinalizeOrder completes the order: the issuer validates domain
	// control by its own rules (or trusts the RA's gate, for the
	// self-signed CA), signs the CSR, and returns the leaf + chain.
	// Returns ErrOrderPending while an asynchronous provider is still
	// processing, and ErrOrderFailed when the order is terminally
	// dead.
	FinalizeOrder(ctx context.Context, req FinalizeOrderRequest) (*IssuedCert, error)

	// GetCACertificate returns the server CA's root certificate PEM.
	// Distinct from the identity CA's root — operators publish this
	// separately so relying parties building TLS trust stores can
	// trust it without trusting the identity CA. Publicly trusted
	// providers (ACME) return their chain root; it is informational
	// there since relying parties already hold it in system stores.
	GetCACertificate(ctx context.Context) (string, error)
}

type TileStorage interface {
	// WriteTile persists the tile bytes at (level, index), overwriting any
	// existing tile at the same address. Data is opaque to this layer.
	WriteTile(ctx context.Context, level, index uint64, data []byte) error

	// ReadTile returns the tile bytes at (level, index). A missing tile
	// must return domain.ErrNotFound so callers can distinguish
	// "gap in the tree" from "storage broken".
	ReadTile(ctx context.Context, level, index uint64) ([]byte, error)
}

type UnitOfWork interface {
	Run(ctx context.Context, fn func(ctx context.Context) error) error
}

type ValidatedCert struct {
	LeafPEM      string
	ChainPEM     string
	CN           string
	SANs         []string
	IssuerDN     string
	ValidFrom    time.Time
	ValidTo      time.Time
	Fingerprint  string // SHA-256, lowercase hex
	SerialNumber string
}

type VerificationMethod struct {
	ID                 string
	Controller         string
	Type               string
	PublicKeyJwk       json.RawMessage
	PublicKeyMultibase string
	Raw                json.RawMessage
}

type VerificationResult struct {
	// AllRequired is true when every record marked Required was found
	// with a matching value.
	AllRequired bool
	Results     []RecordVerification
}