ConnectorClasstypeno test imports ittype ConnectorClass = "cloud" | "identity" | "code-host" | "hr" | "endpoint" | "ticketing" | "network-device" | "vulnerability";What a connector connects to.
The governance of observation (commons integrations 0002-integrations-governance): what a connector is allowed to be and to read, as data that names no vendor, no HTTP and no file path. A connector has a class, one read-only contract, a credential reference with its least-privilege scope, a cadence, the kinds of entity it may produce and the fields that are never kept, labels in the world's terms, and a policy for the trust it places in the system it reads.
Every list is a closed union with an exhaustive switch where it is read; the policy data of a consumer (a fleet's paths, an estate's labels, a catalogue of controls) is attached by the consumer and is not in this module.
ConnectorClasstypeno test imports ittype ConnectorClass = "cloud" | "identity" | "code-host" | "hr" | "endpoint" | "ticketing" | "network-device" | "vulnerability";What a connector connects to.
CONNECTOR_CLASSESconstconst CONNECTOR_CLASSES: readonly ConnectorClass[]The classes of system a connector observes: cloud, identity, code host, HR, endpoint and the like.
ServiceModeltypeno test imports ittype ServiceModel = "IaaS" | "PaaS" | "SaaS";The service models of NIST SP 800-145.
Labelstypeno test imports ittype Labels = { readonly serviceModels: readonly ServiceModel[]; readonly categories: readonly string[] };The labels of a connector in the world's terms: its service models and the categories a consumer's own vocabulary (an analyst's, a catalogue's) names.
Accesstypeno test imports ittype Access = "read";The only thing a connector may do to a system it observes.
Granttypeno test imports ittype Grant = { readonly resource: string; readonly access: Access };One grant of the least-privilege scope: a resource the credential must reach, named in the system's own words, and read access.
Scopetypeno test imports ittype Scope = { readonly grants: readonly Grant[] };The least privilege a connector needs: its grants, all read.
ReadOnlyContracttypeno test imports ittype ReadOnlyContract = { readonly writes: "never"; readonly tokenEndpoints: readonly string[] };The read-only contract: a connector never changes what it observes, and this is a value so that a conformance check can hold it.
EntityKindtypeno test imports ittype EntityKind = "person" | "account" | "device" | "repository";The kinds of entity an observation may carry.
ENTITY_KINDSconstno test imports itconst ENTITY_KINDS: readonly EntityKind[]The kinds of entity that observing produces: person, account, device and repository.
FieldPatterntypeno test imports ittype FieldPattern =
| { readonly kind: "exact"; readonly text: string; readonly why: string }
| { readonly kind: "contains"; readonly text: string; readonly why: string };What the denylist matches: a field name exactly, or a field name containing the text, ignoring case.
Denylisttypeno test imports ittype Denylist = { readonly patterns: readonly FieldPattern[] };The fields that are never kept, whichever connector reads them.
GENERIC_DENYLISTconstno test imports itconst GENERIC_DENYLIST: DenylistThe generic denylist: personal, compensation and secret fields. A connector may add to it and never remove from it.
isDeniedfunctionfunction isDenied(list: Denylist, field: string): booleanWhether a field name is denied by a denylist.
denylistWithconstconst denylistWith: (extra: readonly FieldPattern[]) => DenylistThe denylist of a connector: the generic one and what the connector adds.
Cadencetypeno test imports ittype Cadence = { readonly every: Duration; readonly staleAfter: Duration };A cadence: how often the system is observed, and after how long an observation is stale.
MAX_STALE_MSconstconst MAX_STALE_MS: numberAn observation is never held fresh for longer than seven days.
CadenceErrortypeno test imports ittype CadenceError =
| { readonly kind: "cadence-text"; readonly error: IdError }
| { readonly kind: "stale-before-every"; readonly every: Duration; readonly staleAfter: Duration }
| { readonly kind: "stale-beyond-cap"; readonly staleAfter: Duration };Why a cadence is refused.
cadencefunctionfunction cadence(every: string, staleAfter?: string | undefined): Result<Cadence, CadenceError>A cadence from every (15m, 6h, 1d) and, where given, staleAfter: by default twice every, never more than seven days, never less than every.
isStaleconstconst isStale: (c: Cadence, at: Instant, now: Instant) => booleanWhether an observation made at at is stale at now.
CredentialFieldtypeno test imports ittype CredentialField = { readonly name: string; readonly secret: boolean; readonly hint: string };A field of the credential a person gives the vault: its name, whether it is secret and a hint. A secret field is never optional.
CredentialSpectypeno test imports ittype CredentialSpec = { readonly ref: CredentialRef; readonly fields: readonly CredentialField[] };The credential a connector needs: where the vault keeps it (a reference, never a value) and its fields.
CredentialSpecErrortypeno test imports ittype CredentialSpecError = { readonly kind: "no-secret-field" } | { readonly kind: "field-without-hint"; readonly name: string } | { readonly kind: "duplicate-field"; readonly name: string };Why a credential spec is refused.
credentialSpecfunctionfunction credentialSpec(ref: CredentialRef, fields: readonly CredentialField[]): Result<CredentialSpec, CredentialSpecError>A credential spec that has at least one secret field, a hint on each field and no field twice.
PinOrigintypeno test imports ittype PinOrigin = "trust-on-first-use" | "preconfigured";How a pinned certificate came to be trusted: the first one seen (trust on first use), or one that was set beforehand.
TlsPolicytypetype TlsPolicy =
| { readonly kind: "system-roots" }
| { readonly kind: "pinned"; readonly origin: PinOrigin; readonly sha256: Sha256 | undefined };How the TLS of a system is trusted.
TransportPolicytypeno test imports ittype TransportPolicy =
| { readonly kind: "https"; readonly hosts: readonly string[]; readonly tls: TlsPolicy }
| { readonly kind: "snmp-v3"; readonly level: "authPriv" };How the system is reached: over HTTPS to listed hosts, or over SNMPv3.
ConnectorGovernancetypeno test imports ittype ConnectorGovernance = {
readonly id: ConnectorId;
readonly title: string;
readonly class: ConnectorClass;
readonly labels: Labels;
readonly contract: ReadOnlyContract;
readonly credential: CredentialSpec;
readonly scope: Scope;
readonly cadence: Cadence;
readonly entities: readonly EntityKind[];
readonly denylist: Denylist;
readonly transport: TransportPolicy;
};The governance of one connector.
GovernanceProblemtypeno test imports ittype GovernanceProblem =
| { readonly kind: "no-scope" }
| { readonly kind: "no-host" }
| { readonly kind: "pin-without-digest"; readonly origin: "preconfigured" }
| { readonly kind: "denylist-weaker"; readonly missing: string }
| { readonly kind: "no-service-model" }
| { readonly kind: "entity-twice"; readonly entity: EntityKind };What is wrong with the governance of a connector.
governanceProblemsfunctionfunction governanceProblems(g: ConnectorGovernance): readonly GovernanceProblem[]Every problem of a connector's governance; none where it may be used.
PinDecisiontypeno test imports ittype PinDecision =
| { readonly kind: "accept" }
| { readonly kind: "remember"; readonly sha256: Sha256 }
| { readonly kind: "refuse"; readonly why: "mismatch" | "no-pin-and-not-first-use" | "not-pinned-policy" };What the next contact with a system does about its pinned certificate.
decidePinfunctionfunction decidePin(policy: TlsPolicy, shown: Sha256, remembered: Sha256 | undefined): PinDecisionWhat a pinned policy does with the digest the system shows and the one remembered (or none): a total function of the policy, the shown digest and what is remembered.