Documentation
¶
Overview ¶
Package compliance is your KYC/KYB onboarding, accreditation records, and the evidence trail behind them.
It mounts the ORG-SCOPED operations surface (/v1/compliance): the company's own KYC/KYB onboarding verification, accreditation STATE TRACKING, and a compliance-scoped read of the tamper-evident audit trail (the SOC 2 posture surface). It is the platform TOOLING a company's compliance team uses to orchestrate licensed verification providers and keep an evidence trail — with professionals in the loop.
THE BOUNDARY (a design invariant baked into the data model and every response). This subsystem ORCHESTRATES providers and TRACKS what they report. It never asserts that a subject, or the org, "is compliant": there is no such value in the model. A verification status is exactly what the licensed provider reported (provider_verified / provider_rejected / manual_review) or pending; an accreditation record states who asserted or confirmed what, by which method — not a platform certification. The legal/regulatory determination belongs to the registered entity and its counsel, never to this platform. Every status-bearing response carries Disclaimer to keep that honest on the wire.
WHAT IT COMPOSES (DRY — it forks none of these):
- apps/idv the ONE identity/business verification seam (Persona / Onfido / Stripe Identity behind a fail-closed interface; the honest Manual provider by default).
- audit.Recorder the ONE tamper-evident audit plane (deps.Audit). Every privileged action (start / decide / callback) is recorded there, referencing opaque ids ONLY — never subject PII.
- cek encryption at rest for the per-deployment store, so subject PII (name/email) is sealed on disk.
Index ¶
- Constants
- func Mount(app cloud.Router, deps cloud.Deps) error
- func Shutdown() error
- type Accreditation
- type AccreditationBasis
- type AccreditationMethod
- type AccreditationStatus
- type Check
- type Store
- func (s *Store) Close() error
- func (s *Store) CreateAccreditation(ctx context.Context, a Accreditation) error
- func (s *Store) CreateCheck(ctx context.Context, chk Check) error
- func (s *Store) CreateSubject(ctx context.Context, sub Subject) error
- func (s *Store) GetAccreditation(ctx context.Context, org, id string) (Accreditation, error)
- func (s *Store) GetCheck(ctx context.Context, org, id string) (Check, error)
- func (s *Store) GetCheckByProviderRef(ctx context.Context, providerRef string) (Check, error)
- func (s *Store) GetCheckByRef(ctx context.Context, org, providerRef string) (Check, error)
- func (s *Store) GetSubject(ctx context.Context, org, id string) (Subject, error)
- func (s *Store) ListAccreditation(ctx context.Context, org string, limit int) ([]Accreditation, error)
- func (s *Store) ListChecks(ctx context.Context, org string, limit int) ([]Check, error)
- func (s *Store) ListSubjects(ctx context.Context, org string, limit int) ([]Subject, error)
- func (s *Store) StatusCounts(ctx context.Context, org string) (map[string]int, error)
- func (s *Store) UpdateAccreditationDecision(ctx context.Context, org, id string, status AccreditationStatus, ...) error
- func (s *Store) UpdateCheckStatus(ctx context.Context, org, id string, status idv.Status, decidedBy string, ...) error
- type Subject
- type SubjectKind
Constants ¶
const Disclaimer = "Hanzo Compliance orchestrates licensed verification providers and records what they report. " +
"It does not determine or certify legal or regulatory compliance — that determination belongs to the registered " +
"entity and its counsel. Statuses are provider-reported or pending, never a platform assertion."
Disclaimer is attached to every status-bearing response. It is the boundary invariant made visible on the wire: statuses are provider-reported, never a platform assertion of legal or regulatory compliance.
Variables ¶
This section is empty.
Functions ¶
func Mount ¶
Mount wires /v1/compliance/* and opens the sealed per-deployment store under {DataDir}/compliance.db. The verification provider is resolved from config (idv.FromConfig): Manual by default, a real provider when named — and FAIL-CLOSED, so a named-but-misconfigured provider fails the mount rather than silently downgrading to Manual.
Types ¶
type Accreditation ¶
type Accreditation struct {
ID string `json:"id"`
Org string `json:"org"`
SubjectID string `json:"subjectId"`
Method AccreditationMethod `json:"method"`
Basis AccreditationBasis `json:"basis"`
Status AccreditationStatus `json:"status"`
EvidenceDocID string `json:"evidenceDocId,omitempty"`
ReviewerSub string `json:"reviewerSub,omitempty"` // org user who recorded a decision
Note string `json:"note,omitempty"` // non-PII operator note
ExpiresAt int64 `json:"expiresAt,omitempty"`
CreatedAt int64 `json:"createdAt"`
UpdatedAt int64 `json:"updatedAt"`
}
Accreditation is a TRACKED accreditation-state record — an evidence entry the org keeps, NOT a platform certification. The underlying figures (income, net worth) are never stored; only the method, category, and who recorded what state. Evidence documents live in the org's sealed data room (EvidenceDocID references one).
type AccreditationBasis ¶
type AccreditationBasis string
Accreditation basis — the CATEGORY of qualification (never the underlying PII figures, which are not stored).
const ( BasisIncome AccreditationBasis = "income" BasisNetWorth AccreditationBasis = "net_worth" BasisLicense AccreditationBasis = "professional_license" BasisEntity AccreditationBasis = "entity" )
type AccreditationMethod ¶
type AccreditationMethod string
Accreditation method — HOW an accreditation state was established. Tracking only.
const ( MethodSelfAttested AccreditationMethod = "self_attested" // the subject asserted it MethodThirdPartyLetter AccreditationMethod = "third_party_letter" // a CPA/attorney letter on file MethodProviderVerified AccreditationMethod = "provider_verified" // a licensed verifier confirmed it )
type AccreditationStatus ¶
type AccreditationStatus string
Accreditation status — the honest TRACKED state. There is no platform "accredited: true": the state is what was asserted or what a reviewer/provider confirmed.
const ( AccAsserted AccreditationStatus = "asserted" // recorded as asserted by the subject AccProviderVerified AccreditationStatus = "provider_verified" // a licensed verifier confirmed it AccReviewerConfirmed AccreditationStatus = "reviewer_confirmed" // an org reviewer confirmed the evidence AccRejected AccreditationStatus = "rejected" // a reviewer/provider rejected it AccExpired AccreditationStatus = "expired" // a prior confirmation has aged out )
type Check ¶
type Check struct {
ID string `json:"id"`
Org string `json:"org"`
SubjectID string `json:"subjectId"`
Kind SubjectKind `json:"kind"`
Provider string `json:"provider"`
ProviderRef string `json:"providerRef,omitempty"`
VerifyURL string `json:"verifyUrl,omitempty"`
Status idv.Status `json:"status"`
DecidedBy string `json:"decidedBy,omitempty"`
CreatedAt int64 `json:"createdAt"`
UpdatedAt int64 `json:"updatedAt"`
DecidedAt int64 `json:"decidedAt,omitempty"`
}
Check is one KYC/KYB verification of a subject through the idv provider. Status is idv.Status — provider-reported or pending, never platform-asserted. DecidedBy records WHO settled a terminal status: the provider name (a hosted decision) or an org reviewer's user id (a recorded manual decision).
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store persists compliance records. ONE SQLite file — the system namespace's "compliance" — born encrypted, so subject PII (name/email) is ENCRYPTED AT REST. Tenant isolation is a physical property: `org` is a column on every table and every read and write is filtered by it. MaxOpenConns(1) serializes writes.
func (*Store) CreateAccreditation ¶
func (s *Store) CreateAccreditation(ctx context.Context, a Accreditation) error
func (*Store) GetAccreditation ¶
func (*Store) GetCheckByProviderRef ¶
GetCheckByProviderRef finds a check by its provider reference across ALL orgs — the lookup a SIGNATURE-authenticated provider webhook needs, since an external provider carries no validated org. The provider reference is a cryptographically-unique token (128 random bits, minted per verification), so the owning org is resolved FROM the matched record: the webhook can only ever touch the one tenant that holds that reference, and a caller cannot probe another tenant by guessing (an unknown ref is a plain not-found). The org on the returned Check is authoritative for the update.
func (*Store) GetCheckByRef ¶
GetCheckByRef finds a check by its provider reference within the org — the lookup a provider webhook (correlated by provider ref) needs. Org-scoped so a webhook for one tenant can never touch another's record.
func (*Store) GetSubject ¶
func (*Store) ListAccreditation ¶
func (*Store) ListChecks ¶
func (*Store) ListSubjects ¶
func (*Store) StatusCounts ¶
StatusCounts returns the per-status tally of checks for the org — the honest posture read (counts of provider-reported states), never a boolean "compliant".
func (*Store) UpdateAccreditationDecision ¶
func (s *Store) UpdateAccreditationDecision(ctx context.Context, org, id string, status AccreditationStatus, reviewerSub string, updatedAt int64) error
UpdateAccreditationDecision records a reviewer's decision on an accreditation record. Org-scoped WHERE — a reviewer can only decide within their own tenant.
func (*Store) UpdateCheckStatus ¶
func (s *Store) UpdateCheckStatus(ctx context.Context, org, id string, status idv.Status, decidedBy string, updatedAt, decidedAt int64) error
UpdateCheckStatus settles a check's status. Org-scoped in the WHERE clause so a caller can only ever move its own tenant's record.
type Subject ¶
type Subject struct {
ID string `json:"id"`
Org string `json:"org"`
Kind SubjectKind `json:"kind"`
Ref string `json:"ref,omitempty"` // the org's own opaque external id for this subject
Email string `json:"email,omitempty"`
Name string `json:"name,omitempty"`
CreatedAt int64 `json:"createdAt"`
UpdatedAt int64 `json:"updatedAt"`
}
Subject is a party the org is verifying as part of its own onboarding/compliance — a team member, vendor, customer, or counterparty. It is the ONE place subject PII (name/email) lives; the store seals it at rest and it is returned only to the owning org. Checks and accreditation records reference a subject by opaque id, so nothing downstream (audit, logs, other records) needs to carry the PII.
type SubjectKind ¶
SubjectKind is the kind of party under verification (individual → KYC, business → KYB). It mirrors idv.Kind so the seam and the record speak one vocabulary.
Source Files