senderidentity

type AccountClassFunc func(ctx context.Context, userID string) (string, error)

type AdoptionEvidence struct {
	Selector      string
	HasPrivateKey bool
}

type Config struct {
	// MaxReconcileAttempts bounds the pending→failed TTL. 0 → default.
	MaxReconcileAttempts int
	// ReaperInterval overrides the orphan-sweep cadence. 0 → default.
	ReaperInterval time.Duration
	// LegacyJobCompat is phase 1 of the two-phase blue/green job-lane rollout
	// (config sender_identity.legacy_job_compat).
	// When true, mutation and reconcile jobs are PRODUCED as the legacy kinds
	// on the default queue — consumable by the previous release — while this
	// binary still CONSUMES both lanes. Deploy this release with the flag on;
	// once it is the stable rollback target, flip the flag off (a config-only
	// deploy) to switch producers to the versioned v2 lane. A rollback of
	// that second deploy lands on a binary that consumes v2, so nothing
	// strands. This only makes the River lanes rollback-compatible: operators
	// must still freeze sender-identity mutations while a pre-ownership worker
	// overlaps or is a possible rollback target (see the deployment design).
	// Default false: single-instance/self-host deployments have no blue/green
	// overlap and want the v2 semantics immediately.
	LegacyJobCompat bool
	// Reclaim is the orphan-identity reclaim policy (config
	// sender_identity.reap_orphans and friends). Its zero value — what every
	// self-host and every deployment that omits the block gets — reclaims
	// nothing, so the reaper's orphan phase stays alert-only exactly as before.
	Reclaim ReclaimConfig
}

type DNSRecord struct {
	Type  string `json:"type"`  // "TXT" | "CNAME" | "MX"
	Name  string `json:"name"`  // record host
	Value string `json:"value"` // record value
}

type DeprovisionArgs struct {
	Domain string `json:"domain"`
}

type DeprovisionWorker struct {
	river.WorkerDefaults[DeprovisionArgs]
	// contains filtered or unexported fields
}

type EventFirer func(ctx context.Context, domain, userID string, status Status, errMsg string)

type FakeProvider struct {
	ProvisionCalls []string
	// ProvisionMetas is index-parallel to ProvisionCalls: the classification
	// metadata each Provision call carried. Recorded separately so existing
	// tests keep asserting on the plain domain list.
	ProvisionMetas   []ProvisionMeta
	StatusCalls      []StatusCall
	DeprovisionCalls []string
	ListCalls        int
	ListPageCalls    int
	InspectCalls     []string
	// contains filtered or unexported fields
}

type IdentityAudit struct {
	// Domain is the provider's identity NAME. It is the value matched against
	// the reclaim zones, not a value derived from e2a's database — the whole
	// point is to decide without trusting a join that may not exist.
	Domain string
	Tags   map[string]string
	// VerifiedForSending mirrors SES's VerifiedForSendingStatus: true means
	// this identity can send mail RIGHT NOW.
	VerifiedForSending bool
}

type LegacyReapWorker struct {
	river.WorkerDefaults[ReapArgs]
	// contains filtered or unexported fields
}

type Manager struct {
	// contains filtered or unexported fields
}

type PostDrainAuditArgs struct {
	Domain string `json:"domain" river:"unique"`
	// Window is the audit's schedule bucket (scheduled-at unix seconds /
	// postDrainConvergenceDelay). It scopes ByArgs uniqueness in time: River's
	// unique state set cannot drop `completed`, so without it a completed
	// audit inside the ~24h retention blocked the next mutation's audit for
	// the same domain. A completed audit's bucket is strictly older than any
	// new mutation's (an audit for bucket B cannot complete before B's start,
	// and any later mutation schedules into a later bucket — modulo replica
	// clock skew, which shrinks that guarantee by the skew), so dedupe can
	// only ever match a still-scheduled job. Mutations straddling a bucket
	// edge produce two audits; the audit is idempotent, so that is noise,
	// not a bug.
	Window int64 `json:"window" river:"unique"`
}

type PostDrainAuditWorker struct {
	river.WorkerDefaults[PostDrainAuditArgs]
	// contains filtered or unexported fields
}

type Provider interface {
	// Provision registers a BYODKIM sending identity for domain, supplying
	// the per-domain DKIM selector + PKCS#1 DER private key that e2a
	// already generated (so DKIM d= aligns with the From domain). An
	// existing untagged identity is adopted in place when it provably
	// matches this selector (see Provider doc); otherwise returns
	// ErrIdentityNotOwned. Returns the initial Result — typically
	// StatusPending — or an error to retry.
	//
	// meta is best-effort classification metadata for the identity being
	// created (see ProvisionMeta and tags.go). Implementations MUST treat
	// every field as optional and MUST NOT fail a provision over it: a
	// partial or wholly empty ProvisionMeta yields a less self-describing
	// identity, never a failed verification.
	Provision(ctx context.Context, domain, dkimSelector string, dkimPrivateKeyDER []byte, meta ProvisionMeta) (Result, error)

	// Status polls the current verification state from the provider.
	// evidence is what e2a has on file for domain (see AdoptionEvidence) —
	// Status needs it to make the same adoption judgement as Provision
	// (including self-healing an ownership tag that was removed out-of-band
	// on an identity e2a otherwise still provably owns). Callers that have no
	// adoption judgement to make for this poll (no selector, or a selector
	// without key material) should pass a zero AdoptionEvidence; this never
	// affects polling an ALREADY-owned identity, whose status reporting
	// doesn't consult it. Returns ErrIdentityNotFound if no identity exists
	// for domain.
	Status(ctx context.Context, domain string, evidence AdoptionEvidence) (Result, error)

	// Deprovision removes the sending identity. A missing identity MUST be
	// reported as success (idempotent teardown).
	Deprovision(ctx context.Context, domain string) error

	// List returns all domain identities visible to the provider principal.
	// It is retained for the phase-1 compatibility worker only; the v2 reaper
	// uses ListPage so one River job cannot inventory the whole provider account.
	// Neither path treats an unledgered identity as its own.
	List(ctx context.Context) ([]string, error)

	// ListPage returns one provider-bounded page plus the opaque continuation
	// token. The v2 orphan audit uses this so one River job never inventories
	// the whole provider account.
	ListPage(ctx context.Context, nextToken string, limit int) (domains []string, followingToken string, err error)

	// InspectIdentity returns the facts the orphan-reclaim decision needs for
	// one identity: its classification tags (tags.go) and whether the provider
	// currently considers it able to SEND. Both must come from a SINGLE
	// provider round trip — a two-call version could observe the tags before
	// and the sending state after a change, and the decision would then be
	// made against a state that never existed at once. Returns
	// ErrIdentityNotFound if no identity exists for domain.
	//
	// Only orphan candidates are inspected (see reapProviderOrphanPage), so
	// the per-candidate cost is bounded by how many orphans exist, not by the
	// size of the provider account.
	InspectIdentity(ctx context.Context, domain string) (IdentityAudit, error)
}

type ProvisionArgs struct {
	Domain string `json:"domain"`
}

type ProvisionMeta struct {
	// UserID is the domain owner's user id (SendingIdentityState.Owner).
	UserID string
	// AccountClass is the owner's usage account class ("standard",
	// "internal", "system", "demo"). Empty means "not known" — not
	// "standard": see the purpose vocabulary above for why the difference
	// matters.
	AccountClass string
}

type ProvisionWorker struct {
	river.WorkerDefaults[ProvisionArgs]
	// contains filtered or unexported fields
}

type RawStore interface {
	WithSendingIdentityMutationLock(ctx context.Context, domain string, fn func(context.Context) error) error
	LoadSendingIdentityState(ctx context.Context, domain string) (incarnation, owner string, verified bool, status, selector string, privateKeyDER []byte, appliedIncarnation string, ledgerUpdatedAt time.Time, err error)
	SetSendingStatusForIncarnation(ctx context.Context, domain, incarnation, status, dkimStatus, mailFromStatus, errMsg string, recordsJSON []byte) error
	TouchSendingCheckedForIncarnation(ctx context.Context, domain, incarnation string) error
	MarkSendingIdentityManaged(ctx context.Context, domain, incarnation string) error
	MarkSendingIdentityApplied(ctx context.Context, domain, incarnation string) error
	SendingIdentityLedgerExpired(ctx context.Context, domain, incarnation string, olderThan time.Duration) (bool, error)
	ObserveSendingIdentityProviderPending(ctx context.Context, domain, incarnation string, olderThan time.Duration) (bool, error)
	ClearSendingIdentityProviderPending(ctx context.Context, domain, incarnation string) error
	ForgetSendingIdentityManaged(ctx context.Context, domain string) error
	FinalizeSendingIdentityTombstone(ctx context.Context, domain string, olderThan time.Duration) error
	SetDomainTeardownState(ctx context.Context, domain string, state domainteardown.State) error
	ListManagedSendingIdentityDomains(ctx context.Context) ([]string, map[string]bool, error)
	ListManagedSendingIdentityDomainsPage(ctx context.Context, afterDomain string, limit int) ([]string, map[string]bool, bool, error)
	LookupManagedSendingIdentityDomain(ctx context.Context, domain string) (bool, bool, error)
	DomainExists(ctx context.Context, domain string) (bool, error)
}

type ReapArgs struct{}

type ReapV2Args struct {
	SweepID       int64  `json:"sweep_id,omitempty" river:"unique"`
	AfterDomain   string `json:"after_domain,omitempty" river:"unique"`
	Phase         string `json:"phase,omitempty" river:"unique"`
	ProviderToken string `json:"provider_token,omitempty" river:"unique"`
}

type ReapWorker struct {
	river.WorkerDefaults[ReapV2Args]
	// contains filtered or unexported fields
}

type ReclaimConfig struct {
	// Enabled arms actual deletion. When false the reaper still runs the whole
	// decision and logs what it WOULD delete, but makes no provider mutation —
	// the observe-only mode an operator runs for days before arming.
	Enabled bool
	// Deployment is this deployment's configured name ("prod" | "staging"),
	// matched against the identity's e2a-env tag. Empty (an unnamed
	// deployment, the self-host default) reclaims nothing: without a name
	// there is no way to tell this deployment's fixtures from another
	// deployment's in a shared AWS account.
	Deployment string
	// Zones bounds reclaim to identity names at or under a DNS zone e2a's own
	// test fixtures live in. This is the strongest guard — a customer domain
	// is never under the test zone — and an EMPTY list means reclaim nothing,
	// never "any zone".
	Zones []string
	// MinAge is how old an identity must be (by its e2a-created stamp) before
	// it can be reclaimed, independent of its expiry tag. <= 0 reclaims
	// nothing: an unset floor is treated as an unconfigured policy, not as a
	// waiver.
	MinAge time.Duration
	// MaxPerSweep caps deletions per REAP JOB INVOCATION (see
	// reapProviderOrphanPage — the orphan phase is paginated across River
	// jobs, so this is deliberately a per-page budget and not a global one).
	// 0 reclaims nothing.
	MaxPerSweep int
}

type ReconcileArgs struct {
	Domain      string `json:"domain"`
	Incarnation string `json:"incarnation,omitempty"`
}

type ReconcileV2Args struct {
	Domain      string `json:"domain"`
	Incarnation string `json:"incarnation"`
}

type ReconcileV2Worker struct {
	river.WorkerDefaults[ReconcileV2Args]
	// contains filtered or unexported fields
}

type ReconcileWorker struct {
	river.WorkerDefaults[ReconcileArgs]
	// contains filtered or unexported fields
}

type Result struct {
	Status         Status      `json:"status"`
	DkimStatus     Status      `json:"dkim_status,omitempty"`
	MailFromStatus Status      `json:"mail_from_status,omitempty"`
	Error          string      `json:"error,omitempty"`
	DNSRecords     []DNSRecord `json:"dns_records,omitempty"`
}

type SESProvider struct {
	// contains filtered or unexported fields
}

type SendingIdentityState struct {
	Incarnation string
	Owner       string
	Verified    bool
	Status      Status
	Selector    string
	PrivateKey  []byte
	// AppliedIncarnation is the ledger's provider-confirmed incarnation ("" if
	// none). Equal to Incarnation only when THIS registration's key was
	// confirmed installed — the gate for the healthy-recheck no-op.
	AppliedIncarnation string
	// LedgerUpdatedAt remains available for diagnostics and adapters. Timeout
	// decisions use Store.SendingIdentityLedgerExpired so clocks are not mixed.
	LedgerUpdatedAt time.Time
}

type Status string

type StatusCall struct {
	Domain   string
	Selector string
	HaveKey  bool
}

type Store interface {
	// WithSendingIdentityMutationLock serializes provider create/delete calls
	// for one domain across processes and passes a context pinned to the lock.
	WithSendingIdentityMutationLock(ctx context.Context, domain string, fn func(context.Context) error) error
	// LoadSendingIdentityState returns the current domain incarnation and its
	// desired provider state. pgx.ErrNoRows means the desired state is absent.
	LoadSendingIdentityState(ctx context.Context, domain string) (SendingIdentityState, error)
	// SetSendingStatus writes a terminal/transition status (+ the per-axis
	// dkim/mailFrom breakdown + error + DNS records) and stamps
	// sending_last_checked_at. dkimStatus/mailFromStatus may be empty ("")
	// when the caller has no per-axis signal (e.g. provision, or a terminal
	// failure with no SES poll); persisting empty lets the read path fall back
	// to the all-or-nothing rollup.
	SetSendingStatus(ctx context.Context, domain, incarnation string, status, dkimStatus, mailFromStatus Status, errMsg string, records []DNSRecord) error
	// TouchSendingChecked stamps sending_last_checked_at without changing the
	// status — used on a still-pending poll.
	TouchSendingChecked(ctx context.Context, domain, incarnation string) error
	// The managed-domain ledger survives domain deletion so exhausted River
	// jobs remain repairable without scanning/deleting unrelated identities in
	// the provider account.
	MarkSendingIdentityManaged(ctx context.Context, domain, incarnation string) error
	MarkSendingIdentityApplied(ctx context.Context, domain, incarnation string) error
	// SendingIdentityLedgerExpired compares entirely on the database clock so
	// application/DB clock skew cannot shorten or extend the pending TTL.
	SendingIdentityLedgerExpired(ctx context.Context, domain, incarnation string, olderThan time.Duration) (bool, error)
	// ObserveSendingIdentityProviderPending persists the first provider-pending
	// observation for a DB-verified identity and reports whether its grace has
	// expired, also using the database clock. Clear removes that drift marker
	// once the provider agrees or a terminal transition is committed.
	ObserveSendingIdentityProviderPending(ctx context.Context, domain, incarnation string, olderThan time.Duration) (bool, error)
	ClearSendingIdentityProviderPending(ctx context.Context, domain, incarnation string) error
	// ForgetSendingIdentityManaged currently has no callers in this package —
	// see the doc comment on *identity.Store's implementation for why it is
	// kept anyway, and why an ownership failure must never call it.
	ForgetSendingIdentityManaged(ctx context.Context, domain string) error
	// FinalizeSendingIdentityTombstone removes the ledger row ONLY when its
	// last mutation (updated_at) is older than olderThan. An audit or sweep
	// that runs inside a later mutation's drain window therefore cannot
	// finalize that mutation's tombstone out from under a still-draining
	// legacy slot; the reaper (or that mutation's own audit) finalizes once
	// the window has truly elapsed.
	FinalizeSendingIdentityTombstone(ctx context.Context, domain string, olderThan time.Duration) error
	SetDomainTeardownState(ctx context.Context, domain string, state domainteardown.State) error
	ListManagedSendingIdentityDomains(ctx context.Context) ([]string, map[string]bool, error)
	ListManagedSendingIdentityDomainsPage(ctx context.Context, afterDomain string, limit int) ([]string, map[string]bool, bool, error)
	LookupManagedSendingIdentityDomain(ctx context.Context, domain string) (needsProvision, found bool, err error)
	// DomainExists reports whether a live domain row exists. The reaper uses
	// it to ALERT on provider identities that are neither ledgered nor backed
	// by a row (pre-upgrade orphans the migration backfill could not see).
	DomainExists(ctx context.Context, domain string) (bool, error)
	// AccountClassForUser returns the owner's usage account class
	// ("standard" | "internal" | "system" | "demo") for the provider's
	// classification tags. An empty string means "not known" and is NOT an
	// error: a store with no account-class source wired (self-host, tests)
	// answers that way, and the provider simply omits the purpose tag.
	AccountClassForUser(ctx context.Context, userID string) (string, error)
}

type SyncArgs struct {
	Domain string `json:"domain"`
}

type SyncWorker struct {
	river.WorkerDefaults[SyncArgs]
	// contains filtered or unexported fields
}