service

package
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 31, 2026 License: MPL-2.0 Imports: 93 Imported by: 0

Documentation

Overview

Package service is the domain layer. Handlers cannot reach the datastore directly: internal/store is importable only by this package (and its own subpackages) — enforced by the import-boundary test. Every data-touching method takes the acting principal, opens a transaction, authorizes inside it (single chokepoint, no cache), and only then calls the store with the minted proof. Middleware extracts artifacts only; there is no authenticated principal outside a transaction.

Index

Constants

View Source
const (
	AdvisoryPublished = "revision.published"
	AdvisoryStaged    = "pending.staged"
	// AdvisoryChanged fires once per changed key when an environment advances.
	// It claims exactly what the emitter knows: THIS CELL MOVED. It does not
	// claim any draft went stale -- the publisher's transaction does not read
	// other principals' markers, so a "pending.stale" event here would assert
	// a fact nobody checked. A subscriber that holds a draft on the named cell
	// derives staleness itself: its own draft plus this event IS the fact.
	AdvisoryChanged = "cell.changed"
	// AdvisoryEnvironmentsChanged invalidates the authorized environment list.
	AdvisoryEnvironmentsChanged = "environments.changed"
)

The advisory event types.

View Source
const (
	CLISessionIdle     = 30 * 24 * time.Hour
	CLISessionAbsolute = 90 * 24 * time.Hour
	// BrowserSessionIdle/Absolute are the browser artifact's clocks. Recorded
	// here beside their sibling so the two are read together; the browser
	// artifact itself is minted by #54's login page.
	BrowserSessionIdle     = 7 * 24 * time.Hour
	BrowserSessionAbsolute = 30 * 24 * time.Hour
	// SlideGranularity bounds how often a read request rewrites the idle
	// clock. Without it every authenticated GET would issue a write; with it
	// the clock is accurate to the minute, which is four orders of magnitude
	// finer than the 30-day window it governs.
	SlideGranularity = time.Minute
	// PasswordMinLength is the ADR's length floor: no composition rules, no
	// forced rotation. Composition rules produce `Password1!`.
	PasswordMinLength = 12
	// AuthorityLifetime is the credential-establishment window — the
	// no-session, no-assurance enrolment authority, and the tightest of the
	// one-shot token expiries.
	AuthorityLifetime = 15 * time.Minute
	// BootstrapLifetime is the first-administrator token's expiry. If it
	// lapses a new one is minted from the CLI on the host; it is never
	// re-displayed.
	BootstrapLifetime = 24 * time.Hour
)

Ops-spec session lifetimes (§ 3). CLI sessions may run longer than browser sessions because a session lifetime is not a plaintext-exposure window — disclosure is independently gated by the reveal ceremony and assurance.

View Source
const (
	MethodLocalPassword = "local-password"
	// MethodLocalPasskey is a discoverable WebAuthn login: user-verifying and
	// inherently multi-factor.
	MethodLocalPasskey = "local-passkey"
)

Authentication methods, matching the wire enum.

View Source
const (
	// § 179 search.
	BudgetSearchRatePerMin     = 30
	BudgetSearchOrgConcurrency = 4
	// § 179 / § 20 export — values export and audit export share this category:
	// 5/min per principal, 2 concurrent per org, 6 concurrent per instance.
	BudgetExportRatePerMin          = 5
	BudgetExportOrgConcurrency      = 2
	BudgetExportInstanceConcurrency = 6
	// § 179 publish.
	BudgetPublishRatePerMin     = 10
	BudgetPublishOrgConcurrency = 4
	// § 179 adapter sync/trigger.
	BudgetAdapterRatePerMin     = 10
	BudgetAdapterOrgConcurrency = 4
	// § 179 machine-fetch aggregates, on top of § 5's per-principal 30/min.
	BudgetMachineFetchOrgPerMin       = 300
	BudgetMachineFetchInstancePerMin  = 1000
	BudgetMachineFetchPrincipalPerMin = 30
	BudgetMachineFetchPrincipalBurst  = 60
	// § 179 fail-closed default for any category not named above.
	BudgetDefaultRatePerMin     = 60
	BudgetDefaultOrgConcurrency = 8
	// § 151 (§ 8) schema-revision rate limit, per project.
	BudgetSchemaRevisionPerHour = 60
	// Transit data plane (transit ADR D9, #156): rate-only, per principal and
	// per org. Under multi-node HA the transit service charges the shared
	// admission counters instead, so node hopping cannot multiply it.
	BudgetTransitRatePerMin    = 600
	BudgetTransitOrgRatePerMin = 6000
	// § 10 signup (ops-spec banner 2026-09-03, #579 d7): rate-only and
	// instance-wide, shared by the `none` and `fresh-org` landings.
	BudgetSignupPerHour = 20
	// Operator mail tests share this per-principal hourly bucket across both routes.
	BudgetMailTestPerHour = 5
)

Ops-spec § 179 / § 20 / § 151 values, exported so the conformance registry's anti-drift test can pin the whole family to the spec in one place.

View Source
const (
	BudgetAuthenticatedAPIPerMin = 300
	BudgetAuthenticatedAPIBurst  = 600
)
View Source
const (
	FileTargetApplied = "applied"
	FileTargetCurrent = "current"
	FileTargetOffline = "offline"
	FileTargetRefused = "refused"
	FileTargetFailed  = "failed"
)

File-target report states: the closed vocabulary a client may assert.

View Source
const (
	// OIDCKind and OAuth2Kind are the identity-key discriminators, spelled once
	// in domain.ProviderKind.
	OIDCKind   = string(domain.ProviderOIDC)
	OAuth2Kind = string(domain.ProviderOAuth2)
)
View Source
const (
	IntentSignIn = "sign-in"
	IntentSignUp = "sign-up"
)

Login intents (#604): recorded on a purpose-login transaction, absent on the wire = sign-in.

View Source
const (
	PinQuotaPerProject     = 100
	DefaultPinLifetimeDays = 180
	MaxPinLifetimeDays     = 365
	DefaultPinLifetime     = DefaultPinLifetimeDays * 24 * time.Hour
	MaxPinLifetime         = MaxPinLifetimeDays * 24 * time.Hour
)
View Source
const (
	RetentionRetained           = store.RetentionRetained
	RetentionCollectionEligible = store.RetentionCollectionEligible
	RetentionAlreadyCollected   = store.RetentionAlreadyCollected
)
View Source
const (
	ReencryptChunkSize  = 100
	ReencryptChunkPause = 100 * time.Millisecond
)

ReencryptChunkSize and ReencryptChunkPause are the ops-spec §9 (§167) bounds on the background rewrap walk: at most 100 rows per chunk transaction, a fixed 100 ms pause between chunks. They are the enforced defaults (a caller may set a smaller chunk or no pause for tests, never a larger chunk); the conformance bound-registry pins these values against drift.

View Source
const (
	DefaultRetentionAge       = 90 * 24 * time.Hour
	DefaultRetentionRevisions = int64(10)
	RetentionBatchSize        = 100
	PruneStaleAfter           = 24 * time.Hour
)
View Source
const (
	// DefaultHistoryLimit is the history page size when a caller names none.
	DefaultHistoryLimit = 100
	// MaxHistoryLimit is the largest history page any surface may ask for.
	MaxHistoryLimit = 500
	// HistoryFromNewest is the first-page cursor: strictly above every
	// revision, so the page starts at the environment's newest.
	HistoryFromNewest = int64(math.MaxInt64)
)
View Source
const (
	DefaultSCIMStaleness = 3 * time.Hour
	DefaultSCIMPageSize  = 200
	// DefaultSCIMCredentialTTL is the lifetime ceiling a mint is clamped to
	// when the instance has not configured one.
	DefaultSCIMCredentialTTL = 365 * 24 * time.Hour
)

Bounds the ops spec owns; chosen here because the code needs non-zero ones to be correct at all, and stated as such rather than left broken. The staleness default follows the ADR's own observation that Entra reconciles at roughly 40 minutes and Okta similarly: a threshold below one full IdP cycle would flag every healthy binding.

View Source
const (
	SCIMWarnOrgScope         = "org_scope"
	SCIMWarnRevealExpanding  = "reveal_expanding"
	SCIMWarnProductionEnv    = "production_environment"
	SCIMWarnPopulatedGroup   = "populated_group"
	SCIMWarnSeverityWarning  = "warning"
	SCIMWarnSeverityCritical = "critical"
)

Closed warning codes. Adding one is a deliberate change to what the surface promises to say, which is why they are an enumeration and not free text at the call site.

View Source
const (
	TransitOpEncrypt          = "encrypt"
	TransitOpDecrypt          = "decrypt"
	TransitOpRewrap           = "rewrap"
	TransitOpDataKey          = "datakey"
	TransitOpDataKeyPlaintext = "datakey-plaintext"
	TransitOpSign             = "sign"
	TransitOpVerify           = "verify"
	TransitOpHMAC             = "hmac"
	TransitOpHMACVerify       = "hmac-verify"

	TransitStateActive          = "active"
	TransitStateRetired         = "retired"
	TransitStateDisabled        = "disabled"
	TransitStatePendingDeletion = "pending-deletion"
	TransitStateDestroyed       = "destroyed"

	MaxTransitKeysPerEnvironment = 256
	MaxTransitVersionsPerKey     = 1024
	MaxTransitCallersPerKey      = 64
	MinTransitRotationPeriod     = time.Hour
	MaxTransitRotationPeriod     = 10 * 365 * 24 * time.Hour
	MinTransitDeletionDelay      = 24 * time.Hour
	MaxTransitDeletionDelay      = 90 * 24 * time.Hour
	DefaultTransitDeletionDelay  = 7 * 24 * time.Hour
	DefaultTransitDataKeyBits    = 256
)

Transit ADR D2 / D9 vocabularies and bounds.

View Source
const (
	HandoffEstablishment = authz.HandoffEstablishment
	HandoffStepUp        = authz.HandoffStepUp
)

The two members, re-exported with it.

View Source
const BackupRetentionCeiling = 180 * 24 * time.Hour

BackupRetentionCeiling is the managed-archive age ceiling. Recovery safety can prevent deletion; that is a persistent breach, never a successful prune.

View Source
const BootstrapTemplate = domain.TemplateOperator

BootstrapTemplate is the role template the first administrator is seeded with: `operator`, at instance scope, expanded from the ADR's own closed table rather than from a bespoke list beside it.

This reconciles two clauses of the permission-model ADR that pull apart at bootstrap, and the reconciliation is stated rather than assumed:

  • Propagations → #16 says the first administrator MUST be bootstrapped "via the `admin` template (so reveal/reveal-history are seeded as separate visible grants)".
  • The template table makes `admin` applicable at org/project scope ONLY, and § Administrative power says instance scope inherits downward, so an instance operator "can reach any org's data through an explicit audited grant, NEVER BY BUNDLE" — while `operator` is defined as the operator set plus `manage-members`, with no disclosure at all.

At bootstrap there is no org for an org-scoped template to attach to, so the two cannot both be satisfied literally at the same moment. The reading taken here: bootstrap seeds `operator` at instance scope — separate visible grants, no disclosure, no tenant data reachable by bundle — and the `admin`-template clause is satisfied where it can be, at ORG scope, when the first administrator creates the first org and applies `admin` to themselves through their instance `manage-members` (the ADR's own unheld-granting power, audited like any other grant). `reveal` and `reveal-history` arrive there, as the separate seeded rows the clause asks for.

The previous bespoke list is gone. It seeded `read`, `reveal` and `reveal-history` AT INSTANCE SCOPE, which is precisely the bundle the ADR forbids: the first administrator held secret access over every org that would ever exist, before any of them did.

View Source
const CLIDeviceLifetime = 15 * time.Minute
View Source
const CLILoginLifetime = 10 * time.Minute
View Source
const CLIReauthLifetime = 5 * time.Minute
View Source
const CredentialEstablishLifetime = 5 * time.Minute
View Source
const DefaultCredentialLifetime = 30 * 24 * time.Hour

DefaultCredentialLifetime is the per-credential default when a mint names none. It is finite by the ADR's rule that "the easy path is bounded and a long-lived credential is a typed choice someone made".

OPERATIONS-SPEC FOG VALUE, chosen here and recorded for ratification: 30 days. Short enough that an unnoticed leak has a bound, long enough that a quarterly rotation cadence does not become a weekly one.

View Source
const DefaultReauthHardCap = 15 * time.Minute

DefaultReauthHardCap bounds the absolute age of a reauthentication window.

It exists because of #54's disposition item 1: with both the idle window and the hard cap at 0, a single-decision (0-window) WebAuthn reauth is minted with hard_expires_at == authenticated_at and is dead the instant it is created — so a protected environment, whose whole point is the 0 window, would be unusable. A hard cap is an absolute bound, never extended by activity, so a non-zero default is the honest value; zero was never a meaningful configuration, it was an unset field.

View Source
const DrillStaleAfter = 90 * 24 * time.Hour

DrillStaleAfter is the ops spec's restore-test cadence (§ 11: quarterly, doctor warns past 90 days).

View Source
const ExpiryWarningWindow = 14 * 24 * time.Hour

ExpiryWarningWindow is how far ahead a live finite credential is flagged as expiring. OPERATIONS-SPEC FOG VALUE, recorded for ratification: 14 days.

The ADR also asks for "an audit event at each threshold", and that half is NOT here. It needs something to notice a threshold crossing when nobody is looking, and this binary has no scheduler, no outbox and no background sweep — a threshold event emitted only when a credential happens to be listed would fire on polling rather than on expiry, which is worse than absent because it looks like coverage. The in-product half the ADR puts first (this field, surfaced on every list and mint response) is complete; the event lands with whatever ticket introduces periodic work.

View Source
const (
	// GateAttemptsPerMinute is the sliding per-(principal, key) allowance for
	// reveal-gated acts. A human tightening a rule does it once; twenty a
	// minute is already automation. Concrete value is this slice's; the ops
	// spec owns it (disposition item).
	GateAttemptsPerMinute = 20
)

The schema-model ADR requires every reveal-gated attempt to be "audited and rate-limited, per key and per principal". Rate limiting is DEFENCE IN DEPTH, never the control — the control is that no predicate result reaches a non-revealer, which is the gate itself. This bounds how fast a holder of `definitions-edit` can hammer the gate for timing signal.

View Source
const LoginChallengeLifetime = 5 * time.Minute

LoginChallengeLifetime bounds a challenge's life, mirroring the WebAuthn ceremony: a challenge not finished inside it is inert.

View Source
const MaxEnvironmentsPerProject = 50

MaxEnvironmentsPerProject is the ops spec's environment-count cap. It is enforced inside the creating transaction, against a count read under the same proof — a check made anywhere else is a check a concurrent create can walk past.

View Source
const MaxGrantsPerOrg = 1000

Refusals. Each is its own sentinel so the transport can map it and a test can assert WHICH rule fired — "the grant was refused" is not an assertion.

Each also WRAPS a domain sentinel, so the transport's uniform writer has a code for it. Left bare they all rendered `internal`, which tells a script the server broke when it had in fact answered correctly — the same defect #48 found when `conflict` and `limit_exceeded` fell through the CLI's status mapping. Every refusal here is decided AFTER authorization succeeded, so it may have its own code without disclosing anything a caller could not already read: shape errors are `invalid`, state refusals are `conflict`, and a triple that is not held is `not found`. MaxGrantsPerOrg is the ops-spec § 8 loud sanity cap on grant rows per organization — it exists to make runaway grant-minting loud, not to ration.

View Source
const MaxImportCandidates = 5000

MaxImportCandidates bounds how many undeclared names one presence read may ask about. It is the import framework's record cap: a caller cannot make the server mint more tokens than an import could ever plan.

View Source
const MaxLiveCredentials = 5

MaxLiveCredentials bounds overlap rotation. Several live credentials is the point — mint-new, update the identity provider, revoke-old — but an unbounded set is a pile of year-long bearers nobody is tracking.

View Source
const MaxLiveDeveloperCredentials = 4
View Source
const MaxOpenPlansPerProject = 20

MaxOpenPlansPerProject is the open-plan quota: at most this many unapplied, unexpired plans per project (#70, ops-spec).

View Source
const MaxPendingPerProject = 100

MaxPendingPerProject is the ops-spec § 8 loud cap on pending versions per project. Per-user working state is separately UNIQUE per (user, project, env, key) by the pending_changes constraint; this bounds the project-wide total so a script cannot flood the draft space.

View Source
const MaxProjectStorageBytes = 4 << 30 // 4 GiB

MaxProjectStorageBytes is the ops-spec § 8 / § 141 per-project storage high-water: a project holding this much stored payload (value cells plus published snapshot entries, ciphertext bytes) refuses NEW publishes. Pinned, cross-checked against the ops-spec value by the bound registry.

View Source
const MaxProvenanceBytes = 256

MaxProvenanceBytes bounds each provenance label (#70, ADR § Provenance).

View Source
const MaxRenderBytesPerTarget = 1 << 20

MaxRenderBytesPerTarget is the ops-spec § 8 per-target render cap: the total delivered bytes for one environment must not exceed the Kubernetes Secret validation limit (1 MiB). A single value is bounded well under it (schema.MaxValueBytes), but even the default project key cap times that is far above it, so the sum is a genuine reachable bound — refused at publish, where the target is not yet committed, rather than at delivery, where it is.

View Source
const (

	// MaxRequestFindings caps findings across one request (ADR §7): a request
	// exceeding it fails closed naming the cap, never a silent truncation.
	// MaxRequestFindings is the per-request finding cap; the MCP write surface
	// bounds its acknowledgement list to it.
	MaxRequestFindings = 100
)
View Source
const MaxResolvedCells = 100_000

MaxResolvedCells is the ops-spec § 8 config-time composability budget: environments × declared keys ≤ 100 000, "the operation that would exceed it (creating the env, declaring the key) is refused loud, naming the budget". Increasing the managed key cap can make this reachable. Key, environment and definitions creation enforce it under the project lock.

View Source
const MaxRulesPerOrg = 1000

MaxRulesPerOrg is the loud sanity cap on rule rows per organization, mirroring MaxGrantsPerOrg: it makes runaway rule minting loud.

View Source
const PairingOriginConfigurationMessage = "Set this instance's public HTTPS address in instance settings before creating an invitation."
View Source
const PairingTLSConfigurationMessage = "" /* 163-byte string literal not displayed */
View Source
const PlanTTL = 24 * time.Hour

PlanTTL is the immutable-plan lifetime (#70, ops-spec). An unapplied plan expires 24h after creation; the hourly GC prunes it.

View Source
const ProjectStorageWarnBytes = 1 << 30 // 1 GiB

ProjectStorageWarnBytes is the ops-spec § 8 / § 141 warn threshold: at this much stored payload the operator surfaces (doctor, metric, UI banner) warn, well before the hard refusal at MaxProjectStorageBytes.

View Source
const ProtectedWindowCap = 0 * time.Second

ProtectedWindowCap is the protected-environment window cap: 0, meaning every disclosure reauthenticates. The permission-model ADR recommends it and the operations spec may narrow it, never widen it.

View Source
const RecoveryBatchSize = 10

RecoveryBatchSize is how many single-use recovery codes a batch holds.

View Source
const RefusalDeadline = 100 * time.Millisecond
View Source
const ResetLifetime = BootstrapLifetime

ResetLifetime is the out-of-band credential-establishment window for an administrator-issued or break-glass reset. Longer than the self-service recovery window because the token is transmitted out of band to the target.

View Source
const (
	SAMLKind = string(domain.ProviderSAML)
)
View Source
const SignupLifetime = 24 * time.Hour
View Source
const TOTPIssuer = "hikyo"

TOTPIssuer is the label shown in the authenticator app's account list. There is no per-instance issuer string in this slice; when instance naming lands it supplies this. ponytail: fixed issuer label; swap for the instance name once one exists.

View Source
const WebAuthnCeremonyLifetime = 5 * time.Minute

WebAuthnCeremonyLifetime bounds a challenge's life. A ceremony not finished inside it is inert, exactly as an expired OIDC transaction is.

Variables

View Source
var (
	// ErrAccessNotRequestable refuses a request in an environment no enabled
	// access policy covers.
	ErrAccessNotRequestable = fmt.Errorf("%w: service: no enabled access policy covers this environment", domain.ErrConflict)
	// ErrAccessExceedsPolicy refuses a request for a capability or duration the
	// covering policy does not offer.
	ErrAccessExceedsPolicy = fmt.Errorf("%w: service: the request exceeds what the access policy offers", domain.ErrInvalid)
	// ErrAccessHumanOnly refuses a machine or session-less caller: temporary
	// access is for humans who can be held to a reason and a reauthentication.
	ErrAccessHumanOnly = fmt.Errorf("%w: service: temporary access is requested and decided by humans in an interactive session", domain.ErrUnauthorized)
	// ErrAccessNotApprover refuses a vote by a principal outside the policy's
	// current approver set.
	ErrAccessNotApprover = fmt.Errorf("%w: service: not an approver of this access policy", domain.ErrUnauthorized)
	// ErrAccessApproverCannotGrant refuses an approval by an approver who could
	// not grant every requested capability themselves: approval never grants
	// what the approver could not.
	ErrAccessApproverCannotGrant = fmt.Errorf("%w: service: an approver may approve only capabilities they could grant", domain.ErrUnauthorized)
	// ErrAccessSelfApproval refuses a requester approving their own request
	// under a policy that does not permit it.
	ErrAccessSelfApproval = fmt.Errorf("%w: service: the requester cannot approve their own access under this policy", domain.ErrUnauthorized)
	// ErrAccessNotBypasser refuses emergency access by a principal the policy
	// does not name.
	ErrAccessNotBypasser = fmt.Errorf("%w: service: not a named emergency-access principal of this policy", domain.ErrUnauthorized)
	// ErrAccessNotYours refuses a cancel by anyone but the requester, and a
	// revoke by anyone but the holder, an approver or a member manager.
	ErrAccessNotYours = fmt.Errorf("%w: service: only the requester, an approver or a member manager may do this", domain.ErrUnauthorized)
)
View Source
var (
	ErrAdvisoryPrincipalLimit = fmt.Errorf("%w: service: advisory connection cap reached for this principal", admission.ErrOverloaded)
	ErrAdvisoryOrgLimit       = fmt.Errorf("%w: service: advisory connection cap reached for this organization", admission.ErrOverloaded)
	ErrAdvisoryInstanceLimit  = fmt.Errorf("%w: service: instance-wide advisory connection cap reached", admission.ErrOverloaded)
)
View Source
var (
	// ErrDeliveryKeyring refuses a fetch on a build with no keyring wired. The
	// change token is KEYED; computing one without a key is not a degraded
	// answer, it is a forgeable one.
	ErrDeliveryKeyring = errors.New("service: the delivery surface has no keyring wired")
	// ErrNotMaterialized refuses a fetch against an environment that has no
	// committed snapshot. Delivery reads only committed, valid snapshots or
	// FAILS CLOSED (flat-model ADR) — it never falls back to live state, which
	// is exactly the unvalidated read the snapshot exists to replace.
	ErrNotMaterialized = errors.New("service: this environment has no published revision yet")
)
View Source
var (
	// ErrProviderHasActiveLeases refuses a provider delete that would strand
	// live leases unless the caller asks to revoke them all.
	ErrProviderHasActiveLeases = fmt.Errorf("%w: provider still has active leases; pass revoke_all to revoke them", domain.ErrConflict)
	// ErrProviderUnreachable reports a provider that could not be reached or
	// authenticated at configuration time. Fail loud: a provider that cannot
	// mint is never recorded as usable.
	ErrProviderUnreachable = fmt.Errorf("%w: dynamic provider unreachable or credential refused", domain.ErrInvalid)
)
View Source
var (
	// ErrTOTPAlreadyEnrolled refuses a second confirmed TOTP factor.
	ErrTOTPAlreadyEnrolled = errors.New("service: a confirmed TOTP factor is already enrolled")
	// ErrNoPendingTOTP refuses a confirm with no enrolment in progress.
	ErrNoPendingTOTP = errors.New("service: no TOTP enrolment is in progress")
	// ErrNoTOTPFactor refuses a step-up or removal with no confirmed factor.
	ErrNoTOTPFactor = errors.New("service: no confirmed TOTP factor")
	// ErrNoProofCredential refuses a mutation the account has no pre-existing
	// credential to authorize.
	ErrNoProofCredential = errors.New("service: no pre-existing credential to authorize this change")
	// ErrTOTPCodeAlreadyUsed refuses a code whose (account, time step) was
	// already consumed by an earlier proof — the SAME code presented twice in
	// its 30-second window (human-auth ADR §141 single-use-per-step, §207 the
	// second disclosure waits for the next step). It wraps domain.ErrConflict, a
	// LOUD post-authentication state refusal on the caller's OWN factor that
	// discloses nothing (a stolen session already knows it just spent the code):
	// classify() maps it to 409 and the uniform writer carries its SafeDetail,
	// unlike the uniform 401 a WRONG code returns.
	ErrTOTPCodeAlreadyUsed = fmt.Errorf("%w: this TOTP code's time step was already used", domain.ErrConflict)
)

Structural factor refusals are loud (400), because the caller is authenticated and acting on their OWN account: naming the state helps them and reveals nothing to anyone else. A bad code or password stays uniform (401, domain.ErrUnauthenticated) so presentation reveals nothing.

View Source
var (
	// ErrIssuerValue refuses an issuer configuration outside its own grammar.
	ErrIssuerValue = fmt.Errorf("%w: service: an issuer needs an https URL, a known type, a JWKS mode and at least one refused audience", domain.ErrInvalid)
	// ErrIssuerInUse refuses deleting an issuer that live bindings still name.
	// Removing it would be an authorization change wearing a configuration
	// change's clothes.
	ErrIssuerInUse = fmt.Errorf("%w: service: live bindings still name this issuer", domain.ErrConflict)
	// ErrNoSuchIssuer refuses a binding naming an issuer the instance does not
	// configure, and an administrative call against an id that is not there.
	ErrNoSuchIssuer = fmt.Errorf("%w: service: no such federation issuer", domain.ErrNotFound)
	// ErrBindingAudience refuses a binding with no audience, or one naming the
	// issuer's default audience. Both are the same rule: audience binding is
	// mandatory and the default is refused.
	ErrBindingAudience = fmt.Errorf("%w: service: a binding must name an audience, and never the issuer's default", domain.ErrInvalid)
	// ErrBindingClaims refuses a binding that pins nothing, or a pin that is
	// not a scalar.
	ErrBindingClaims = fmt.Errorf("%w: service: a binding must pin at least one claim, each a string, integer or boolean", domain.ErrInvalid)
	// ErrBindingImmutableID refuses a binding that does not pin the immutable
	// identifiers its platform exposes. It is its own refusal because the remedy
	// is specific: pin the numeric id, not the name — a renamed-and-reused
	// repository path or a recreated ServiceAccount otherwise inherits the
	// binding.
	ErrBindingImmutableID = fmt.Errorf("%w: service: a binding must pin the immutable identifiers this issuer exposes", domain.ErrInvalid)
	// ErrBindingEventName refuses a CI binding that does not pin `event_name`.
	// This is the load-bearing refusal of the whole CI story: without the pin,
	// a `pull_request_target` token carries the ordinary ref-form subject a
	// production binding names.
	ErrBindingEventName = fmt.Errorf("%w: service: a Forgejo or GitHub Actions binding must pin `event_name`", domain.ErrInvalid)
	// ErrBindingSubject refuses an empty subject. There is no wildcard: the
	// absence of a subject is not "any subject".
	ErrBindingSubject = fmt.Errorf("%w: service: a binding must name a subject", domain.ErrInvalid)
	// ErrNoSuchBinding refuses a replacement naming a credential this service
	// account does not hold.
	ErrNoSuchBinding = fmt.Errorf("%w: service: no such binding", domain.ErrNotFound)
)
View Source
var (
	// ErrNoSuchCapability refuses a capability outside the ADR's closed set.
	ErrNoSuchCapability = fmt.Errorf("%w: service: no such capability", domain.ErrInvalid)
	// ErrCapabilityScope refuses an atom granted deeper than its own level —
	// `manage-projects` on one environment is not a narrower grant, it is a
	// grant that can never be evaluated.
	ErrCapabilityScope = fmt.Errorf("%w: service: this capability cannot be granted at this scope", domain.ErrInvalid)
	// ErrGrantorLacksCapability is the project-scope bound: `manage-members`
	// held at PROJECT scope may grant only capabilities the grantor currently
	// holds at or above the target scope. A stolen project-admin account is
	// therefore not automatic full compromise of that project's secrets.
	ErrGrantorLacksCapability = fmt.Errorf("%w: service: a project-scope member manager may grant only capabilities it holds", domain.ErrConflict)
	// ErrMachineCapability is the normative machine allowlist refusing. It is
	// a refusal by the API, not a convention.
	ErrMachineCapability = fmt.Errorf("%w: service: this capability is not on the principal class's allowlist", domain.ErrConflict)
	// ErrMachineRevealOptIn refuses `reveal` on a workload or automation
	// principal while the project's machine-reveal opt-in is off
	// (source-of-truth ADR: "an explicit, documented, per-project operator
	// opt-in, never a default"). The grant API names the opt-in so the
	// operator learns which act admits it, rather than a bare allowlist refusal.
	ErrMachineRevealOptIn = fmt.Errorf("%w: service: reveal on a machine principal requires the project's machine-reveal opt-in", domain.ErrConflict)
	// ErrMachineRevealHistoryPin refuses `reveal-history` on a workload unless
	// an active pin routes a non-current revision to that workload.
	ErrMachineRevealHistoryPin = fmt.Errorf("%w: service: reveal-history on a workload requires an active non-current revision pin", domain.ErrConflict)
	// ErrMachineScope refuses a machine grant that is SHALLOWER than its
	// class admits — a workload outside an explicit (project, environment),
	// or automation above project depth. The allowlist bounds which
	// capability; this bounds where, which is the other half of the same ADR
	// sentence and the half that makes `read` at org scope not a workload
	// grant at all.
	ErrMachineScope = fmt.Errorf("%w: service: this principal class may not hold a grant at this scope depth", domain.ErrConflict)
	// ErrMachineProject refuses a machine grant in a project other than the
	// one the principal's existing grants already sit in. The ADR bounds
	// automation to "one project's scope"; the first grant fixes which.
	ErrMachineProject = fmt.Errorf("%w: service: this machine principal is already bound to a different project", domain.ErrConflict)
	// ErrSystemCreatedOnly refuses a grant the system creates with its own
	// binding — `scim-provision` rides its SCIM binding (#73), never this API.
	ErrSystemCreatedOnly = fmt.Errorf("%w: service: this capability is system-created with its binding, never granted through this API", domain.ErrConflict)
	// ErrLastMemberManager is the lockout invariant: removing the last
	// `manage-members` holder at org or instance scope is refused, because an
	// unadministrable org is a support incident with no in-product recovery.
	ErrLastMemberManager = fmt.Errorf("%w: service: this is the last manage-members holder at this scope", domain.ErrConflict)
	// ErrNoSuchGrant refuses a revoke of a triple that is not held.
	ErrNoSuchGrant = fmt.Errorf("%w: service: no such grant", domain.ErrNotFound)
	// ErrUnknownPrincipal refuses a grant to a principal that does not exist.
	ErrUnknownPrincipal = fmt.Errorf("%w: service: no such principal", domain.ErrInvalid)
	// ErrDisclosureAuthority is the machine-identities ADR's mint/widen
	// refusal: the actor holds `manage-identities` but not the disclosure
	// capability over an environment the operation would make reachable.
	//
	// It is ErrConflict, exactly like ErrGrantorLacksCapability above and for
	// the same reason: authorization for the OPERATION succeeded — the actor
	// administers this project's identities and can list them — so the
	// nonexistent mask would be a lie they could disprove with their next
	// call, and 403 is reserved on tenant routes for the assurance refusal.
	// What refuses is the resulting state, which is what `conflict` means
	// everywhere else in this surface.
	ErrDisclosureAuthority = fmt.Errorf("%w: service: this operation would make plaintext reachable in an environment you may not disclose", domain.ErrConflict)
	// ErrReauthRequired is the reauthentication conjunct refusing. The
	// underlying cause (no window, expired, spent, wrong unit) is deliberately
	// not distinguished on the wire: the remedy is the same in every case.
	ErrReauthRequired = fmt.Errorf("%w: service: reauthenticate over the environments this operation makes reachable, then retry", domain.ErrConflict)
)
View Source
var (
	// ErrServiceAccountName refuses a name outside the grammar. It is
	// ErrInvalid, decided before any tenant resolution, so it discloses
	// nothing about what exists.
	ErrServiceAccountName = fmt.Errorf("%w: service: a service-account name must be 1-64 characters", domain.ErrInvalid)
	// ErrServiceAccountKind refuses a kind outside the closed set. Kind is
	// immutable after creation, so this is the only gate there is.
	ErrServiceAccountKind = fmt.Errorf("%w: service: a service account is `workload` or `automation`", domain.ErrInvalid)
	// ErrCredentialCap refuses a mint that would exceed the instance's
	// concurrent-credential cap. Overlap-based rotation needs room; an
	// unbounded mint loop is a different thing.
	ErrCredentialCap = fmt.Errorf("%w: service: this service account already holds the maximum number of live credentials", domain.ErrLimitExceeded)
	// ErrIndefiniteNotAllowed refuses an indefinite credential where the
	// instance opt-in is off. It is a SEPARATE refusal from the lifetime
	// clamp on purpose: raising the ceiling can never manufacture indefinite.
	ErrIndefiniteNotAllowed = fmt.Errorf("%w: service: this instance does not permit indefinite credentials", domain.ErrConflict)
	// ErrCredentialLifetime refuses a non-positive requested lifetime.
	ErrCredentialLifetime = fmt.Errorf("%w: service: a credential lifetime must be positive", domain.ErrInvalid)
	// ErrNoSuchCredential refuses a revoke of a credential this service
	// account does not hold.
	ErrNoSuchCredential = fmt.Errorf("%w: service: no such credential", domain.ErrNotFound)
	// ErrPolicyValue refuses an instance policy outside its own bounds.
	ErrPolicyValue = fmt.Errorf("%w: service: a credential policy needs a positive lifetime ceiling and credential cap", domain.ErrInvalid)
)
View Source
var (
	// ErrProviderExists reports a slug already in use.
	ErrProviderExists = errors.New("service: an OIDC provider with that slug already exists")
	// ErrProviderNotFound reports an unknown provider slug.
	ErrProviderNotFound = errors.New("service: no such OIDC provider")
	// ErrIssuerImmutable reports an attempt to change a provider's issuer (A3).
	ErrIssuerImmutable = errors.New("service: a provider issuer is immutable; delete and recreate")
	// ErrProviderRace reports a lost CAS on a provider reconfigure.
	ErrProviderRace = errors.New("service: provider row changed underneath this write")
	// ErrProviderDiscovery reports a discovery failure at provider write time.
	ErrProviderDiscovery = errors.New("service: provider discovery failed")
	// ErrPairwiseClientID refuses a client_id change on a provider whose
	// discovery advertises pairwise subjects only while identities are linked
	// under its issuer (#588 d2): every linked subject is bound to the old
	// client registration. Remedy: delete and recreate the provider, which
	// strands them explicitly. The ErrIssuerImmutable shape.
	ErrPairwiseClientID error = pairwiseClientIDError{}
	// ErrLastCredential refuses unlinking the last remaining credential.
	ErrLastCredential = errors.New("service: cannot unlink the last remaining credential")
	// ErrIdentityNotFound reports an unknown identity id on unlink.
	ErrIdentityNotFound = errors.New("service: no such linked identity")
	// ErrReauthWindowClosed refuses OIDC reauth where the effective window is 0
	// (a 0-window gate needs WebAuthn, which alone can bind the enumerated unit).
	ErrReauthWindowClosed = errors.New("service: reauthentication window is 0; a WebAuthn ceremony is required here")
)

Loud, structural OIDC refusals for callers acting on their own instance config or account - not the uniform pre-auth mask.

View Source
var (
	ErrPKIIssuerNotFound = fmt.Errorf("%w: PKI issuer not found", domain.ErrNotFound)
	ErrPKIIssuerExists   = fmt.Errorf("%w: a PKI issuer with this name already exists; rotate it instead", domain.ErrConflict)
	ErrPKIIssuerState    = fmt.Errorf("%w: the PKI issuer version is not in the required lifecycle state", domain.ErrConflict)
	ErrPKIIssuerRace     = fmt.Errorf("%w: the PKI issuer changed underneath this write", domain.ErrConflict)
	ErrPKIIssuerLive     = fmt.Errorf("%w: the PKI issuer version still has unexpired certificates requiring CRL coverage; wait for them to expire", domain.ErrConflict)
	ErrPKIIssuerHeld     = fmt.Errorf("%w: the PKI issuer is held after a restore; reconcile revocations and release its hold (`hikyo pki issuer release-hold`) before issuing certificates or signing fresh CRLs", domain.ErrConflict)
	ErrPKINoActiveIssuer = fmt.Errorf("%w: none of the profile's issuers has an active version", domain.ErrConflict)
	ErrPKIProfileExists  = fmt.Errorf("%w: a certificate profile with this name already exists", domain.ErrConflict)
	ErrPKIProfileRace    = fmt.Errorf("%w: the certificate profile changed underneath this write", domain.ErrConflict)
	ErrPKIBindingExists  = fmt.Errorf("%w: the profile is already bound to this scope", domain.ErrConflict)
	ErrPKIBindingTarget  = fmt.Errorf("%w: the organization, project or environment does not exist", domain.ErrInvalid)
	ErrPKIRenewWindow    = fmt.Errorf("%w: the certificate is not inside its profile's renewal window", domain.ErrConflict)
	ErrPKICertificateNot = fmt.Errorf("%w: the certificate is not in a state that allows this", domain.ErrConflict)
	ErrPKISigning        = fmt.Errorf("%w: the certificate was not issued; the issuer changed while signing", domain.ErrConflict)
)
View Source
var (
	// ErrNoReauthWindow refuses a disclosure with no live window for (session,
	// environment). Fail-closed: at a 0 effective window with no WebAuthn ceremony
	// there is no window at all, which is the default state (B18).
	ErrNoReauthWindow = errors.New("service: no live reauthentication window for this disclosure")
	// ErrReauthWindowExpired refuses a disclosure whose window has lapsed (idle or
	// hard cap) or whose credential epoch is inert.
	ErrReauthWindowExpired = errors.New("service: the reauthentication window has expired")
	// ErrReauthUnitMismatch refuses a single-decision window presented for a
	// different enumerated unit than its ceremony bound (B11).
	ErrReauthUnitMismatch = errors.New("service: this reauthentication authorized a different disclosure")
	// ErrReauthWindowSpent refuses a single-decision window already consumed (B11
	// double-spend).
	ErrReauthWindowSpent = errors.New("service: this reauthentication has already been spent")
)
View Source
var (
	// ErrRuleMachine refuses a rule for a machine principal. The machine
	// widening gate diffs per-environment reach and would undercount a
	// key-narrowed machine reveal, so machines keep legacy grants only.
	ErrRuleMachine = fmt.Errorf("%w: service: member access rules are for people; machine principals keep their grants", domain.ErrInvalid)
	// ErrNoSuchRule is a revoke of a rule that does not exist (or that the
	// caller may not reach, indistinguishably).
	ErrNoSuchRule = fmt.Errorf("%w: service: no such rule", domain.ErrNotFound)
)
View Source
var (
	ErrSAMLTransientNameID     = errors.New("service: transient SAML NameID is unsupported")
	ErrSAMLEmailNameIDDisabled = errors.New("service: emailAddress SAML NameID requires provider opt-in")
	ErrSAMLNameIDFormat        = errors.New("service: unsupported SAML NameID format")
	ErrSAMLProviderNotFound    = errors.New("service: no such SAML provider")
	ErrSAMLMetadataExpired     = errors.New("service: SAML provider metadata has expired")
	ErrSAMLResponse            = errors.New("service: SAML response refused")
	ErrSAMLRelayState          = errors.New("service: invalid SAML RelayState")
	ErrSAMLSigningKey          = errors.New("service: SAML request signing key is unavailable")
	ErrSAMLReauthNoPolicy      = errors.New("service: SAML provider has no assurance policy; reauthentication is refused")
	ErrSAMLReauthNoEnvironment = errors.New("service: SAML reauthentication requires an environment_id")
)
View Source
var (
	ErrSAMLProviderRace               = errors.New("service: SAML provider row changed underneath this write")
	ErrSAMLEntityIDImmutable          = errors.New("service: a SAML provider entityID is immutable; delete and recreate")
	ErrSAMLMetadataSource             = errors.New("service: SAML metadata source must be exactly one file document or URL")
	ErrSAMLMetadataFetch              = errors.New("service: SAML metadata fetch failed")
	ErrSAMLMetadataInvalid            = errors.New("service: SAML metadata is invalid")
	ErrSAMLMetadataSignatureDowngrade = errors.New("service: unsigned SAML metadata cannot replace signed metadata")
)
View Source
var (
	ErrSAMLSPKeyNotFound = errors.New("service: SAML SP key not found")
	ErrSAMLSPKeyState    = errors.New("service: SAML SP key is not in the required lifecycle state")
	ErrSAMLSPKeyRace     = errors.New("service: SAML SP key changed underneath this write")
)
View Source
var (
	// ErrSCIMProviderUnavailable is the fail-closed refusal of §1: while the
	// referenced provider is disabled or removed, the binding's ENTIRE wire
	// surface refuses — read and write alike — state is preserved for repair,
	// and the binding sits in the attention state naming it.
	ErrSCIMProviderUnavailable = fmt.Errorf("%w: service: this SCIM binding's identity provider is disabled or removed", domain.ErrConflict)
	// ErrSCIMSubjectSource refuses a binding whose declared subject source is
	// not usable as identity material — `userName` by name (§5.1).
	ErrSCIMSubjectSource = fmt.Errorf("%w: service: this SCIM attribute may not be a subject source", domain.ErrInvalid)
	// ErrSCIMSubjectWriteOnce refuses a mutation that would change a resource's
	// derived subject. An IdP-side identifier migration is the rebinding hazard
	// the identity model exists to prevent; deprovision-and-recreate is the
	// explicit path.
	ErrSCIMSubjectWriteOnce = fmt.Errorf("%w: service: a SCIM user's subject is write-once; deprovision and recreate instead", domain.ErrConflict)
	// ErrSCIMSubjectMissing refuses a resource carrying no value at the
	// binding's declared subject-source path.
	ErrSCIMSubjectMissing = fmt.Errorf("%w: service: this SCIM resource carries no value at the binding's subject source", domain.ErrInvalid)
	// ErrSCIMPasswordRefused refuses the SCIM `password` attribute BY NAME
	// (§5.2). Provisioning never establishes credentials.
	ErrSCIMPasswordRefused = fmt.Errorf("%w: service: the SCIM password attribute is not supported; provisioning never establishes credentials", domain.ErrInvalid)
	// ErrSCIMUserNameRequired refuses a create or PUT with no `userName`.
	ErrSCIMUserNameRequired = fmt.Errorf("%w: service: userName is required", domain.ErrInvalid)
	// ErrSCIMNestedGroup refuses a group-typed member reference (§6): v1 is
	// flat, and Okta and Entra provision direct user members.
	ErrSCIMNestedGroup = fmt.Errorf("%w: service: nested group members are not supported", domain.ErrInvalid)
	// ErrSCIMUnknownMember refuses a member reference resolving to no user this
	// binding provisioned. The IdP can only reference ids this server minted.
	ErrSCIMUnknownMember = fmt.Errorf("%w: service: this member reference names no user provisioned by this binding", domain.ErrInvalid)
	// ErrSCIMUniqueness refuses a duplicate `userName`, displayName or
	// subject-source collision.
	ErrSCIMUniqueness = fmt.Errorf("%w: service: this value is already taken in this binding", domain.ErrConflict)
	// ErrSCIMMappingScope refuses a mapping row naming a scope outside the
	// binding's own org — refused at authoring time and again at sync time (§1).
	ErrSCIMMappingScope = fmt.Errorf("%w: service: a mapping row may not name a scope outside the binding's org", domain.ErrInvalid)
	// ErrSCIMTemplate refuses a mapping row targeting a template that is not
	// structurally mappable — `operator` is instance-scoped and out of an org
	// binding's reach by construction (§3).
	ErrSCIMTemplate = fmt.Errorf("%w: service: this role template cannot be mapped by a SCIM binding", domain.ErrInvalid)
	// ErrSCIMIndefiniteRefused refuses an indefinite credential while the
	// instance opt-in is off — which it is by default.
	ErrSCIMIndefiniteRefused = fmt.Errorf("%w: service: indefinite provisioning credentials require the instance opt-in", domain.ErrConflict)
	// ErrSCIMBindingMismatch is the credential-versus-binding-path refusal
	// (§8). It is an AUTHENTICATION failure, never a SCIM 400: there is no
	// ambient routing by credential.
	ErrSCIMBindingMismatch = fmt.Errorf("%w: service: this credential does not belong to the addressed binding", domain.ErrUnauthenticated)
)

Refusals. Each is its own sentinel, wrapping a domain sentinel so the transport has a code for it and a test can assert WHICH rule fired.

View Source
var (
	// ErrProtectedWindowCap refuses raising a protected environment's
	// reauthentication window above the protected cap.
	ErrProtectedWindowCap = fmt.Errorf("%w: service: a protected environment's reauthentication window may not exceed the protected cap", domain.ErrInvalid)
	// ErrNegativeWindow refuses a negative window: 0 already means "every
	// disclosure", and there is nothing below it.
	ErrNegativeWindow = fmt.Errorf("%w: service: a reauthentication window cannot be negative", domain.ErrInvalid)
	// ErrNoReauthHardCap refuses leaving an environment at an effective
	// window of 0 while no hard cap is configured — the resulting window
	// would be born expired, and a disclosure gate that silently cannot be
	// satisfied is worse than one that refuses loudly.
	ErrNoReauthHardCap = fmt.Errorf("%w: service: an effective reauthentication window of 0 requires a non-zero reauthentication hard cap", domain.ErrConflict)
	// ErrEnvironmentSettingsRace refuses a stale full-replacement request whose
	// reviewed protection flag changed before the write transaction.
	ErrEnvironmentSettingsRace = fmt.Errorf("%w: service: environment settings changed after review", domain.ErrConflict)
)
View Source
var (
	// ErrSSHProfileDisabled refuses issuance through a disabled profile. It is
	// only reachable by a listed requester, so it discloses nothing.
	ErrSSHProfileDisabled = fmt.Errorf("%w: the SSH profile is disabled", domain.ErrConflict)
	// ErrSSHCAHasProfiles refuses a CA delete while live profiles use it.
	ErrSSHCAHasProfiles = fmt.Errorf("%w: the SSH CA still has profiles; delete them first", domain.ErrConflict)
	// ErrSSHKRLTooLarge reports a KRL over its bound: refused, never truncated.
	ErrSSHKRLTooLarge = fmt.Errorf("%w: the key revocation list exceeds its bound of %d serials", domain.ErrConflict, sshca.MaxKRLSerials)
)
View Source
var (
	// ErrTransitForbidden is a post-authorization refusal by the key's own
	// policy: the key does not allow the operation, or its caller entries
	// exclude the caller. It renders 403 and names nothing.
	ErrTransitForbidden = fmt.Errorf("%w: the key's policy does not permit this caller or operation", domain.ErrUnauthorized)
	// ErrTransitCustodyUnavailable is the fail-closed answer when the key's
	// custody provider cannot serve. It never falls back to another provider.
	ErrTransitCustodyUnavailable = fmt.Errorf("transit: %w", transit.ErrUnavailable)
)
View Source
var (
	// ErrWebAuthnUnavailable is returned when the relying party was not
	// configured at boot, so no WebAuthn route can serve.
	ErrWebAuthnUnavailable = errors.New("service: webauthn is not configured on this instance")
	// ErrNoWebAuthnCeremony refuses a finish with no live matching ceremony.
	ErrNoWebAuthnCeremony = errors.New("service: no matching webauthn ceremony")
	// ErrNoPasskey refuses a step-up, reauth or removal with no usable passkey.
	ErrNoPasskey = errors.New("service: no usable passkey")
	// ErrPasskeyOnlyViolation refuses a mutation that would leave a passwordless
	// account without >=2 discoverable authenticators and a current recovery
	// batch, in either direction (B4/B13).
	ErrPasskeyOnlyViolation = errors.New("service: a passwordless account needs at least two discoverable passkeys and a current recovery-code batch")
)

Structural refusals are loud (400) — the caller owns the account, so naming the state helps them and reveals nothing. A bad assertion stays uniform (401) so presentation reveals nothing.

View Source
var (
	// ErrOriginNotAllowed is a handoff attempted from an origin this instance
	// has not consented to. It is refused at the TRANSACTION, not merely at
	// CORS: CORS controls what a browser may read, never what a token may do.
	// It wraps ErrUnauthorized so the transport answers 403 rather than a
	// fault: the caller IS refused, and a 500 would read as "we broke".
	ErrOriginNotAllowed = fmt.Errorf("%w: that origin is not on the workspace allowlist", domain.ErrUnauthorized)
	// ErrHandoffInvalid is the uniform refusal for every unusable handoff:
	// unknown, expired, already consumed, or presented with the wrong verifier.
	// One error for all of them deliberately — distinguishing them would be an
	// oracle for transactions in flight.
	// Uniform 403, like the origin refusal: an unusable handoff must not be
	// distinguishable from a refused one, and neither is a server fault.
	ErrHandoffInvalid = fmt.Errorf("%w: the handoff transaction is not valid", domain.ErrUnauthorized)
	// ErrConnectionRevoked is a revoke of a connection already revoked.
	ErrConnectionRevoked = fmt.Errorf("%w: that connection credential is already revoked", domain.ErrConflict)
)
View Source
var ErrAccountExists = errors.New("an account with that username already exists")

ErrAccountExists reports a username collision.

View Source
var ErrAdapterBootstrapCeremonyUnspecified = errors.New("service: zero-target adapter credential ceremony is not specified")
View Source
var ErrAlreadyLinked = errors.New("service: that identity is already linked")

ErrAlreadyLinked refuses linking an identity that is already bound.

View Source
var ErrApprovalGatedMultiEnv = fmt.Errorf("%w: service: a publish into a policy-covered environment must address that environment alone", domain.ErrInvalid)

ErrApprovalGatedMultiEnv refuses a multi-environment publish that touches a policy-covered environment: a request pins exactly one environment's change set, so a covered publish must address that environment alone.

View Source
var ErrApprovalNotSatisfied = fmt.Errorf("%w: service: the approval request has not reached its quorum", domain.ErrConflict)

ErrApprovalNotSatisfied is returned when a named request cannot be merged: not enough approvals from currently-eligible approvers, or a reject stands.

View Source
var ErrApprovalRequired = fmt.Errorf("%w: service: this environment requires an approved change-request before publish", domain.ErrConflict)

ErrApprovalRequired is the named refusal a publish returns when a policy covers the environment but no completed approval or bypass is presented. It wraps ErrConflict so the wire answers 409: the caller's selection is fine, but the environment's policy has not been satisfied yet.

View Source
var ErrBackupDurabilityUnconfirmed = errors.New("backup artifact published but durability unconfirmed")

ErrBackupDurabilityUnconfirmed means publication succeeded but syncing its directory failed. The named artifact is retained for operator inspection; callers must not record a successful export from this result.

View Source
var ErrBadPurpose = errors.New("service: OIDC purpose must be login, link, reauth, establish or claim")

ErrBadPurpose refuses an unknown OIDC transaction purpose loudly: it is a caller programming error, not a probe outcome.

View Source
var ErrCLILoginBrowserFactorRequired = cliLoginBrowserFactorRequired{}

ErrCLILoginBrowserFactorRequired permits recovery of a valid pending request after fresh browser sign-in. Invalid references never return this refusal.

View Source
var ErrCLILoginInvalid = fmt.Errorf("%w: invalid or spent CLI login transaction", domain.ErrUnauthorized)
View Source
var ErrCLIReauthInvalid = errors.New("service: invalid or spent CLI reauthentication handoff")
View Source
var ErrCSRFMismatch = errors.New("service: the presented synchronizer token is not this session's")

ErrCSRFMismatch is a LIVE browser session that did not present its own synchronizer token. It is deliberately distinct from domain.ErrUnauthenticated: the transport treats a session that resolves to nothing as "no cookie leg" and lets the request through to be judged on its own merits, and treats this as the refusal the CSRF gate exists for. On the wire both are the same uniform 401.

View Source
var ErrClassificationInUpdate = fmt.Errorf(
	"%w: classification changes only through the reclassification ceremony, never an ordinary update",
	domain.ErrInvalid)

ErrClassificationInUpdate is the ordinary-update refusal (mvp-boundary C1: "classification changes only via the reclassification ceremony"), returned by the transport when an ordinary key update carries a classification field at all — equal to the current value or not. Refusing the FIELD rather than the CHANGE keeps the refusal free of a read, and keeps a caller from discovering the current classification by probing which values are accepted.

View Source
var ErrCommonPassword = passwordPolicyError("that password appears in a list of commonly used passwords; choose another")

ErrCommonPassword refuses a password from the bundled list. Like the length floor it is loud and specific: this is the caller's own input, evaluated before anything is looked up, so naming the rule helps the human and reveals nothing about what exists.

View Source
var ErrCredentialRace = errors.New("service: credential row changed underneath this write")

ErrCredentialRace reports a verifier row that moved underneath a compare-and-swap. It is loud rather than retried-into-silence: the caller decides, and a pass that cannot converge fails rather than skipping.

View Source
var ErrDeploymentPreparationExpired = errors.New("deployment preparation expired; prepare again")

ErrDeploymentPreparationExpired requires another read-only preparation and a fresh exact-MFA decision. Uncommitted private source proofs are intentionally unavailable after restart; already committed signed commands remain replayable.

View Source
var ErrDeploymentSourcesPending = errors.New("deployment sources are not yet installed")

ErrDeploymentSourcesPending means the current process has not proved the requested installed selectors and must not acknowledge their generation.

View Source
var ErrEnvironmentNotForPurpose = fmt.Errorf("%w: environment_id is only valid with purpose reauth", domain.ErrInvalid)

ErrEnvironmentNotForPurpose refuses an environment_id on a login or link start: only reauth scopes a window, and the transaction CHECK refuses the field on every other purpose. It depends on the request body alone, so it is the one start refusal that is not folded into the uniform 401.

View Source
var ErrExportUnpaired = fmt.Errorf("service: audit export stopped by authorization loss; started event has no completed pair")

ErrExportUnpaired marks an export that stopped without its terminal OUTCOME event: mid-export revocation. The started event without a completed event is the ADR's visible reconciliation case, and the denial event the revoked page-authorization flushed records the cause. A completed event cannot be written here without fabricating authority the principal no longer holds — proofs are grant-evaluated per page, and the audit-model ADR's single enumerated proof-free writer is the denial writer alone (amendment part 4). Stated as a deviation in the handoff.

View Source
var ErrInstanceAlreadyBootstrapped = errors.New(
	"this instance already has an account; `admin create` mints the FIRST administrator only")

ErrInstanceAlreadyBootstrapped refuses a second first-administrator. It is loud: silently minting another instance-wide admin because a command was run twice is exactly the surprise a secrets control plane must not have.

View Source
var ErrLockoutRetained = fmt.Errorf(
	"%w: service: this grant is retained because it is the org's last manage-members grant; grant manage-members to another principal and the retention releases itself",
	domain.ErrConflict)

ErrLockoutRetained refuses a hand revocation of a grant held only by a `lockout-retention` origin. The origin is system-owned: it is not hand-revocable and not IdP-addressable, and the cure is adding another `manage-members` holder to the org (ADR §2.4).

View Source
var ErrNoAdvisoryChannel = errors.New("service: this instance serves no advisory channel")

ErrNoAdvisoryChannel refuses a subscription on a build with no channel wired. A stream that silently never delivers is worse than one that refuses: the client cannot tell it from a quiet project, so it stops polling too.

View Source
var ErrNoCeremonySeam = errors.New("service: the value surface has no reauthentication seam wired")

ErrNoCeremonySeam is a wiring fault, never a caller's problem: a value surface built without an Auth cannot run the reveal guard, and a disclosure surface with a missing guard must refuse loudly rather than disclose.

View Source
var ErrNoResetTarget = errors.New("service: no such account to reset")

ErrNoResetTarget is the ONE uniform refusal for every network reset that must not enumerate the target's grant shape: an unknown principal, a machine principal with no account, and — collapsed here so it is indistinguishable on the wire (B2) — a target holding an instance capability, which has no network reset path at all (ADR - Recovery), break-glass only. The operator learns to use break-glass from the docs, not from a differential response; the durable audit still records the true cause (see stageResetRefusal).

View Source
var ErrNoRestorePending = errors.New("this instance has no outstanding restore to reconcile")

ErrNoRestorePending reports a reconciliation attempted on an instance that has not been restored. It is loud rather than a no-op: "reconciled" would be a claim about a ceremony that had no subject.

View Source
var ErrNoSecretToProve = errors.New("restored instance holds no secret value to prove readable")

ErrNoSecretToProve reports that the restored instance holds no `secret` value at all, so the drill cannot prove protected values are readable. It is loud: a drill that "passed" only because there was nothing to open proves nothing about the recovery.

View Source
var ErrOAuth2ProviderExists = fmt.Errorf("%w: service: an OAuth2 provider with that slug already exists", domain.ErrConflict)
View Source
var ErrOAuth2Reauth = errors.New("service: OAuth2 cannot reauthenticate; enrol WebAuthn or TOTP")
View Source
var ErrPairingInvalid = fmt.Errorf("%w: pairing invitation or proof is not valid", domain.ErrUnauthenticated)
View Source
var ErrPairingOriginConfiguration = pairingIdentityRefusal{/* contains filtered or unexported fields */}

These closed, post-authorization refusals expose operator remedies without disclosing resolver errors, certificate contents or proxy credentials.

View Source
var ErrPairingTLSConfiguration = pairingIdentityRefusal{}
View Source
var ErrPrivacyLastManager = errors.New("privacy: assign another manage-members holder before restricting this principal")
View Source
var ErrProtectedDestination = fmt.Errorf("%w: destination environment is protected", domain.ErrConflict)

ErrProtectedDestination refuses a copy into a protected environment that carries no confirmation. It is a distinct sentinel because the caller CAN see the environment — the refusal is a ceremony, not an authorization answer, so masking it as nonexistent would be a lie.

It wraps domain.ErrConflict: a protected destination is a POST-authorization state refusal (the caller passed the destination formula, the environment's protection flag then refused the act), which is exactly what conflict is — "the current state of this resource refuses the request". Wrapping no sentinel would classify() it as an internal fault and answer 500 for a documented refusal. The conflict message is uniform on the wire, but the refusal carries the destination environment id as a SafeDetail (see ProtectedDestinationRefusal): the id came from the caller's OWN request and the refusal is post-authorization, so naming it discloses nothing.

View Source
var ErrReauthNoEnvironment = errors.New("service: OIDC reauthentication requires an environment_id")

ErrReauthNoEnvironment refuses a reauth with no environment scope.

View Source
var ErrReauthNoPolicy error = reauthNoPolicyError{}

ErrReauthNoPolicy refuses starting a reauth against a provider with no assurance policy (A5, #588 d4): such a row is not reauth-capable, so the start refuses by name, before any round-trip and before any row is written, naming the remedy. The caller has already authenticated a session through this very provider, so the refusal discloses nothing to a prober.

View Source
var ErrReauthProofRequired = fmt.Errorf(
	"%w: service: this operation requires reauthentication; present your TOTP code, or your password if you have no factor",
	domain.ErrInvalid)

ErrReauthProofRequired refuses a reauthentication-gated operation presented without its proof. It is `invalid`, not `unauthenticated`: the session is fine, the request is incomplete.

View Source
var ErrRegistrationPolicyRace = fmt.Errorf("%w: service: the registration policy changed underneath this write", domain.ErrConflict)

ErrRegistrationPolicyRace reports that the policy moved underneath the write (a concurrent edit or delete); the caller re-reads and retries.

View Source
var ErrRegistrationProofUnavailable = fmt.Errorf(
	"%w: service: reauthentication is required to change a registration policy and is not configured",
	domain.ErrConflict)

ErrRegistrationProofUnavailable refuses a network mutation when no reauthentication library is wired: the gate fails closed, never open.

View Source
var ErrRemoteCap = fmt.Errorf("%w: the configured remote cap is reached", domain.ErrLimitExceeded)

ErrRemoteCap is the refusal at the configured-entry cap.

View Source
var ErrRemoteUnverified = fmt.Errorf("%w: the verifying directory fetch did not succeed — the entry was not created", domain.ErrConflict)

ErrRemoteUnverified is `remote add` whose verifying fetch did not return a usable listing. The entry is NOT committed: an entry that has never authenticated once is a credential nobody has checked.

View Source
var ErrReportTooLarge = fmt.Errorf("service: a delivery-target report is at most %d bytes", deliverytarget.MaxReportBytes)

ErrReportTooLarge is the size refusal (413).

View Source
var ErrReportVocabulary = errors.New("service: the report carries a value outside the advertised vocabulary")

ErrReportVocabulary is the whole-report vocabulary refusal (422). The wrapping error's SafeDetail names the refused JSON member, never its value.

View Source
var ErrSCIMCredentialLimit = fmt.Errorf(
	"%w: service: this binding already holds the maximum number of live provisioning credentials; revoke one first",
	domain.ErrLimitExceeded)

ErrSCIMCredentialLimit refuses a mint at the cap, by name.

View Source
var ErrSCIMGroupMemberLimit = store.ErrSCIMGroupMemberLimit

ErrSCIMGroupMemberLimit exposes the repository refusal at the service boundary without requiring the wire transport to import the datastore.

View Source
var ErrSCIMNoTarget = fmt.Errorf(
	"%w: service: the members filter names no member of this group", domain.ErrNotFound)

ErrSCIMNoTarget refuses a filtered member removal naming somebody who is not a member. RFC 7644 calls that `noTarget`, and answering success would tell the identity provider a removal happened that did not.

View Source
var ErrSCIMOriginOnly = fmt.Errorf(
	"%w: service: this grant is held by SCIM provisioning; remove the user from the group at the identity provider, or edit or delete the mapping row",
	domain.ErrConflict)

ErrSCIMOriginOnly refuses a HAND revocation of a grant whose only live origins are system-owned, naming the two real remediations (ADR §4).

Before this ticket such a revoke fell through to ErrNoSuchGrant, which is a different statement: "you do not hold that" versus "you hold it, and this is not the lever that removes it". An administrator told the first would go looking for a grant that is right there on the membership line.

View Source
var ErrSCIMScopeAncestry = fmt.Errorf(
	"%w: service: this scope does not belong to the binding's organisation", domain.ErrInvalid)

checkMappingScope refuses a row naming a scope outside the binding's org and a template no binding may map. Both are checked at AUTHORING time and again at sync time, because the mapping table and the group memberships move independently. ErrSCIMScopeAncestry refuses a mapping row whose project or environment does not actually live under the binding's org.

View Source
var ErrSelfConfigFenced = fmt.Errorf("%w: fenced", ErrSelfConfigUnavailable)

ErrSelfConfigFenced is the subset of ErrSelfConfigUnavailable that names a known fenced state: the managed configuration is suspended, restoring, on another topology, or not yet reconciled to the active generation. Callers that must tell "fenced by design" from a fault (a failed metadata read, a runtime that never loaded) test for this, not for the broader error.

View Source
var ErrSelfConfigMailLimited = errors.New("configuration test email rate or concurrency limit reached")
View Source
var ErrSelfConfigUnavailable = errors.New("runtime configuration is not ready; retry after reconciliation")
View Source
var ErrSelfConnected = &detailErr{err: fmt.Errorf("%w: that URL is this instance", domain.ErrConflict), detail: "self_connected"}

ErrSelfConnected is `remote add` pointed at this instance. It is refused at the AUTHENTICATED FETCH, by instance identity — never guessed from the URL, which a DNS change can make wrong in either direction.

View Source
var ErrStalePending = fmt.Errorf("%w: service: pending change is stale", domain.ErrConflict)

ErrStalePending reports the optimistic freshness check failing: the environment advanced after the draft was staged, or the named version was superseded by a newer edit from its owner. Loud, never a silent rebase -- binding to version ids rather than to entry identity is what stops a publisher committing a value they never previewed. It wraps domain.ErrConflict so the wire answers 409, the code the contract declares for it -- an unmapped sentinel here answered 500 and read as a server fault rather than the caller's stale selection.

View Source
var ErrStalePreview = fmt.Errorf("%w: service: publish preview is missing or stale", domain.ErrConflict)
View Source
var ErrStructuralGrant = fmt.Errorf(
	"%w: service: this grant is structural to a SCIM binding; delete the binding to retire it",
	domain.ErrConflict)

ErrStructuralGrant refuses a hand revocation of a provisioning connection's own `scim-provision` grant. It is released only by the binding-deletion state machine (§6), which retires the principal and the grant atomically.

View Source
var ErrWeakPassword = passwordPolicyError(fmt.Sprintf("password must be at least %d characters", PasswordMinLength))

ErrWeakPassword is a loud, specific refusal — password policy is evaluated at set time, where naming the rule helps the human and reveals nothing.

Functions

func BudgetClassOf

func BudgetClassOf(op authz.Operation) (reason string, known bool)

BudgetClassOf reports an operation's classification and whether it is known. For the conformance totality test only.

func CanonicalEnvironmentSet

func CanonicalEnvironmentSet(environmentIDs []string) string

CanonicalEnvironmentSet is the one spelling of the full adapter ceremony scope: sorted, de-duplicated and newline-joined.

func CanonicalKeySet

func CanonicalKeySet(keyIDs []string) string

CanonicalKeySet is the one spelling of an enumerated key set: sorted and newline-joined. Both the consent (written onto the window at approval) and the disclosure (presented at consumption) go through it, so the comparison is a SET comparison and not an ordering accident. An empty set canonicalizes to "", which is what a consent naming no keys stores.

func CanonicalOrigin

func CanonicalOrigin(raw string) (string, error)

CanonicalOrigin normalizes and validates an origin to scheme://host[:port].

A path, query, fragment or userinfo is REFUSED rather than stripped: an allowlist entry is an exact origin, and silently normalizing one is how an operator ends up trusting something other than what they typed.

func CheckPassword

func CheckPassword(password string) error

CheckPassword applies the whole policy.

func CompleteRestore

func CompleteRestore(now time.Time, m store.Manifest) tx.RestoreFn

CompleteRestore is the closure the restore transaction runs against the restored state, before it is committed or published. It advances the credential epoch and retires pending human proofs, invalidates restored adapter and dynamic-provider credentials, holds restored CA issuers, and writes the reconstruction record in that same act. Any failure is returned to abort the restore transaction.

It is a package-level function rather than a method because it has no datastore of its own to hold: the whole point is that it runs on somebody else's transaction.

func ProtectedDestinationRefusal

func ProtectedDestinationRefusal(envID domain.EnvID) error

ProtectedDestinationRefusal builds the protected-destination refusal for a destination environment. It wraps ErrProtectedDestination (so errors.Is and classify() see the conflict sentinel) and rides the destination id on the SafeDetail channel the uniform writer honours for conflict — the id is caller-supplied and the refusal is post-authorization, so it identifies the destination without disclosing anything the caller could not already see.

func RequestableCapabilities

func RequestableCapabilities() []string

RequestableCapabilities returns the closed set in its canonical order.

func SelfConfigMailConfigured

func SelfConfigMailConfigured(sc *SelfConfig) (func(context.Context) (bool, error), error)

SelfConfigMailConfigured adapts the active runtime configuration to the registration mailer predicate: the captured bundle's prepared mail client (mailer-seam 7.3 clauses 1 and 2). Only the known fenced states (a suspended, restoring or unreconciled configuration) read "unconfigured": the policy must not open on a mail transport the runtime will not use. Every other capture failure is a fault and propagates.

func SetSCIMPhaseObserver

func SetSCIMPhaseObserver(fn func(phase string, state map[string]int)) func()

SetSCIMPhaseObserver installs the observer and returns a restore func. It is exported for internal/isolation only; nothing in production installs one.

The callback runs SYNCHRONOUSLY INSIDE the transaction, so returning from it is what lets the transaction continue: a fixture that blocks in it has paused the act at that boundary. `state` carries the facts the phase is about, read under the transaction's own proof — the only way to see uncommitted intermediate state, since an outside reader sees the pre-transaction snapshot on both engines.

func TrackCallerActivity

func TrackCallerActivity(ctx context.Context) context.Context

TrackCallerActivity prepares a request context to receive the narrow result of successful in-transaction authentication.

Types

type Access

type Access struct {
	DB   *store.DB
	Auth *Auth
	Now  func() time.Time
}

Access is the temporary-access service.

func (*Access) Cancel

func (s *Access) Cancel(ctx context.Context, actor Actor, scope domain.Scope, requestID string) (AccessRequestView, error)

Cancel withdraws the caller's own open request. Idempotent on a request the caller already cancelled.

func (*Access) CreatePolicy

func (s *Access) CreatePolicy(ctx context.Context, actor Actor, scope domain.Scope, input AccessPolicyInput) (AccessPolicyView, error)

CreatePolicy adds an access policy. Project-scoped, manage-members.

func (*Access) DeletePolicy

func (s *Access) DeletePolicy(ctx context.Context, actor Actor, scope domain.Scope, id string) error

DeletePolicy removes a policy. Open requests under it fail closed at their next decision; granted access keeps its absolute expiry.

func (*Access) DrainExpired

func (s *Access) DrainExpired(ctx context.Context) error

DrainExpired runs at most 100 expiry batches, stopping when fewer than 100 requests expire in a batch. It returns the first batch error; reaching the batch limit returns nil even if a backlog remains.

func (*Access) EmergencyAccess

func (s *Access) EmergencyAccess(ctx context.Context, actor Actor, scope domain.Scope, input AccessRequestInput) (AccessRequestView, error)

EmergencyAccess takes the policy's capabilities without the quorum. Only a named emergency-access principal of the covering, enabled policy may; it takes a current reauthentication ceremony bound to the environment and a reason, and it is time-bound like every temporary grant. Capabilities must be a nonempty subset of the offer. A zero DurationSeconds defaults to one hour capped by the policy; an explicit duration outside the policy bounds wraps ErrAccessExceedsPolicy. It never touches the policy. Human-session, policy, capability, reason, and authorization checks return the same errors as Request; an unlisted principal gets ErrAccessNotBypasser. Missing Auth returns ErrNoCeremonySeam. Reauthentication, storage, and audit errors are propagated; success consumes a single-decision window or refreshes a sliding window, and records a granted request, temporary grants, and an access.bypassed event.

func (*Access) ExpireDue

func (s *Access) ExpireDue(ctx context.Context) (int, error)

ExpireDue processes at most 100 due requests and returns the number expired in the committed batch, or zero and the transaction error. Requests are due at or after their deadline. Open requests whose review window lapsed resolve expired; granted requests past their absolute expiry release their rows, rotate the holder's sessions and resolve expired. The chokepoint already stopped honoring the rows at expires_at; this is the bookkeeping and the evidence. Under HA the scheduler context's lease fences the batch.

func (*Access) ListPolicies

func (s *Access) ListPolicies(ctx context.Context, actor Actor, scope domain.Scope) ([]AccessPolicyView, error)

ListPolicies returns the project's access policies with member sets and available principal names and records a policy-read audit event. It requires manage-members at the project; authorization, lookup, and audit errors propagate.

func (*Access) OperationalCounts

func (s *Access) OperationalCounts(ctx context.Context) (open, active int64, err error)

OperationalCounts returns the installation-wide open-request and active-grant counts for the label-free /metrics gauges. Open includes requests awaiting the expiry sweep. Active counts granted requests whose expiry is strictly after now, rather than individual capability rows. Transaction and query errors are returned; counts should be used only when err is nil.

func (*Access) Queue

func (s *Access) Queue(ctx context.Context, actor Actor, scope domain.Scope) (AccessQueue, error)

Queue returns up to 200 of an environment's requests, newest first, and its covering offer. Offer is nil when no policy covers the environment; a disabled environment policy still takes precedence over a project-wide policy. Approval counts are recomputed for open requests without resolving stale ones. Authorization, storage, and view-loading errors are returned to the caller.

func (*Access) Request

func (s *Access) Request(ctx context.Context, actor Actor, scope domain.Scope, input AccessRequestInput) (AccessRequestView, error)

Request files a request for temporary access in the addressed environment. The request is immutable: capabilities, duration, reason and the policy version it was filed under are written once and never updated. The caller must be a human in a session with read access to the environment. DurationSeconds must be positive and within the covering policy's maximum; capabilities must be a nonempty subset of its offer. The sanitized reason must contain 1 to 512 bytes. A successful request records an access.requested event. Missing or disabled policies return ErrAccessNotRequestable; invalid capability or duration choices wrap ErrAccessExceedsPolicy, and invalid reasons wrap domain.ErrInvalid. Authorization, storage, and audit errors are propagated.

func (*Access) Revoke

func (s *Access) Revoke(ctx context.Context, actor Actor, scope domain.Scope, requestID string) (AccessRequestView, error)

Revoke ends granted access before its expiry: the rows are released, the holder's sessions rotate, and the request resolves revoked. The holder may relinquish their own access; an eligible approver of the policy or a member manager of the project may revoke anyone's. Idempotent on an already revoked request.

func (*Access) UpdatePolicy

func (s *Access) UpdatePolicy(ctx context.Context, actor Actor, scope domain.Scope, id string, input AccessPolicyInput) (AccessPolicyView, error)

UpdatePolicy replaces a policy's fields and member sets and bumps its version, making open requests pinned to the old version stale for new votes. Granted access keeps its absolute expiry: a policy change never extends it.

func (*Access) Vote

func (s *Access) Vote(ctx context.Context, actor Actor, scope domain.Scope, requestID, decisionRaw string) (AccessRequestView, error)

Vote records one approver's decision. The approver must be a currently eligible member of the policy's approver set. An approval also requires authority to grant every requested capability and permission for self-approval when the caller is the requester. The approve that reaches the quorum writes the time-bound grant rows in the same transaction. A repeated identical decision returns the current view without requiring renewed approver eligibility; a conflicting one wraps domain.ErrConflict. A rejection resolves the request immediately. New votes require an open, unexpired review window. A missing, disabled, or changed policy commits invalidation before returning domain.ErrConflict. Invalid decisions wrap domain.ErrInvalid; human-session, eligibility, authorization, storage, and audit errors are propagated.

type AccessOffer

type AccessOffer struct {
	PolicyID           string
	PolicyVersion      int64
	Capabilities       []string
	MaxDurationSeconds int
	MinApprovals       int
	Enabled            bool
	// CallerMayBypass reports whether the caller is a named emergency-access
	// principal, so a surface can offer the emergency path only to them.
	CallerMayBypass bool
}

AccessOffer is what a requester may ask for in one environment: the covering policy's requestable surface, without its approver roster.

type AccessPolicyInput

type AccessPolicyInput struct {
	EnvironmentID      string // "" = every environment in the project
	Capabilities       []string
	MaxDurationSeconds int
	MinApprovals       int
	AllowSelfApproval  bool
	RequestTTLSeconds  int
	Enabled            bool
	Approvers          []ApprovalApproverSpec
	Bypassers          []string
}

AccessPolicyInput is a policy create/update from the admin surface.

type AccessPolicyView

type AccessPolicyView struct {
	PrincipalNames     map[string]string
	ID                 string
	EnvironmentID      string
	Capabilities       []string
	MaxDurationSeconds int
	MinApprovals       int
	AllowSelfApproval  bool
	RequestTTLSeconds  int
	Enabled            bool
	Version            int64
	Approvers          []ApprovalApproverSpec
	Bypassers          []string
	CreatedAt          time.Time
	UpdatedAt          time.Time
}

AccessPolicyView is a policy as the admin surface reads it.

type AccessQueue

type AccessQueue struct {
	Offer    *AccessOffer
	Requests []AccessRequestView
}

AccessQueue is an environment's request queue with the offer that governs it.

type AccessRequestInput

type AccessRequestInput struct {
	Capabilities    []string
	DurationSeconds int
	Reason          string
}

AccessRequestInput is a request from the requester.

type AccessRequestView

type AccessRequestView struct {
	CanApprove       bool
	RequesterName    string
	ID               string
	EnvironmentID    string
	PolicyID         string
	PolicyVersion    int64
	Requester        string
	Capabilities     []string
	DurationSeconds  int
	Reason           string
	Bypassed         bool
	State            string
	InvalidatedCause string
	ResolvedBy       string
	CreatedAt        time.Time
	ReviewExpiresAt  time.Time
	GrantedAt        *time.Time
	ExpiresAt        *time.Time
	ResolvedAt       *time.Time
	MinApprovals     int
	Approvals        int
	Votes            []AccessVoteView
}

AccessRequestView is a request as the review surface reads it.

type AccessVoteView

type AccessVoteView struct {
	PrincipalName string
	PrincipalID   string
	Decision      string
	CreatedAt     time.Time
}

AccessVoteView is one recorded vote.

type AccountProfile

type AccountProfile struct {
	Username         string
	DisplayName      string
	Email            *string
	EmailVerified    bool
	Managed          bool
	UsernameEditable bool
}

AccountProfile is the authenticated holder's profile. Username and display name are editable (ProfileUpdate); Email is read-only, nil when none. When EmailVerified it is the login email, written only by verified local sign-up (#608) and never here; otherwise it is a legacy contact address, display-only and never used to sign in. It is never a recovery or linking identifier.

type Actor

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

Actor is who is asking, resolved INSIDE the operation's own transaction.

This type exists because of a real defect two reviewers found independently: the transport used to resolve the session in one transaction and then hand a bare principal id to a service that opened another. Between them a session could be revoked, expire, have its generation advanced or its credential epoch bumped — and the operation would still authorize against the principal that resolution had already decided on. A principal id crossing a transaction boundary IS the cross-request authorization cache the permission model forbids; it just looks like an argument.

The zero value resolves to nothing, so a caller that forgets to set one gets a refusal rather than an anonymous success.

func Bearer

func Bearer(artifact string) Actor

Bearer is the network path: a presented session artifact, resolved at the chokepoint inside whichever transaction the operation opens.

func FederatedActor

func FederatedActor(c FederatedCaller) Actor

FederatedActor is the machine federation path (#62): an externally issued OIDC ID token whose signature, issuer, audience-independent timing and Hikyo caps have ALREADY been validated, outside any transaction, because validating them needs the network and a JWKS fetch inside a write transaction would stall every writer on sqlite.

What has NOT happened yet is the part that must not be cached: resolving which service account the `(issuer, subject)` pair names, checking the binding is live under the current credential epoch, and evaluating the binding's own predicate — audience, every pinned claim, the CI event rule, the post-restore `iat` floor. All of that happens at the chokepoint inside the operation's transaction, which is what makes revocation bite at the next fetch.

It is therefore NOT the cross-transaction authorization cache the permission model forbids: what crosses the boundary is a validated set of external claims, not a resolved principal, and no Hikyo state was read to produce it.

func LocalPrincipal

func LocalPrincipal(p domain.PrincipalID) Actor

LocalPrincipal is the below-the-network path: a principal the caller already established by other means — the isolation harness, and local authority verbs that run on the server's own host.

It bypasses session resolution by construction, which is exactly why the import-boundary test refuses internal/server the right to name it. A transport that could build one could authorize as anybody.

func PairedConnectionActor

func PairedConnectionActor(token, proof string) Actor

PairedConnectionActor requires a fresh request proof at the transaction chokepoint.

func SCIMCredentialActor

func SCIMCredentialActor(presented, bindingID string) Actor

SCIMCredentialActor is the SCIM wire path: a presented provisioning credential plus the binding the request addressed. Both are resolved inside the operation's own transaction, exactly like a session bearer, so a credential revoked between resolution and authorization cannot still authorize the operation.

type AdapterConflictArtifact

type AdapterConflictArtifact = store.AdapterConflictArtifact

AdapterConflictArtifact intentionally shares a store-owned type with transport mapping. This sanctioned seam follows the system-architecture ADR; boundary_test.go enforces that handlers never import internal/store directly.

type AdapterConflictEntry

type AdapterConflictEntry = store.AdapterConflictEntry

AdapterConflictEntry intentionally shares a store-owned type with transport mapping. This sanctioned seam follows the system-architecture ADR; boundary_test.go enforces that handlers never import internal/store directly.

type AdapterKeySelection

type AdapterKeySelection struct {
	// Names are exact key names; an unknown name is refused by name.
	Names []string
	// Include and Exclude are bounded glob patterns over key names
	// (`*`, `?`, `[...]` as path.Match understands them).
	Include []string
	Exclude []string
	// Classification keeps only keys of that classification when set.
	Classification string
}

AdapterKeySelection is the configuration-time convenience for choosing a target's key subset (#157). It resolves against the project catalogue when the target is saved; the resolved ids become the explicit membership and the selection itself is never stored. A key created later that would have matched is not added: the deployment-adapter ADR binds membership to immutable ids and refuses any living "all"-shaped set.

type AdapterMove

type AdapterMove = store.AdapterMove

AdapterMove intentionally shares a store-owned type with transport mapping. This sanctioned seam follows the system-architecture ADR; boundary_test.go enforces that handlers never import internal/store directly.

type AdapterMoveTarget

type AdapterMoveTarget = store.AdapterMoveTarget

AdapterMoveTarget exposes pending target metadata through the service seam, keeping transport mappings and fixtures independent of store imports.

type AdapterPlanResult

type AdapterPlanResult struct {
	ArtifactID string
	Plan       adapter.Plan
}

type AdapterRecord

type AdapterRecord = store.AdapterRecord

AdapterRecord intentionally shares a store-owned type with transport mapping. This sanctioned seam follows the system-architecture ADR; boundary_test.go enforces that handlers never import internal/store directly.

type AdapterTarget

type AdapterTarget = store.AdapterTarget

AdapterTarget intentionally shares a store-owned type with transport mapping. This sanctioned seam follows the system-architecture ADR; boundary_test.go enforces that handlers never import internal/store directly.

type AdapterTargetFlagPatch

type AdapterTargetFlagPatch struct {
	VariableProtected, VariableHidden, VariableExpand *bool
}

AdapterTargetFlagPatch preserves omitted transport fields during target updates. A nil patch means the caller supplied complete target state.

type AdapterTargetInput

type AdapterTargetInput struct {
	AllowEnvironmentCreate bool
	EnvironmentID          string
	DestinationKind        string
	DestinationOwner       string
	DestinationName        string
	DestinationEnvironment string
	Visibility             string
	SelectedRepositoryIDs  []int64
	NamePrefix             string
	KeyIDs                 []string
	// GitLab only: the environment_scope ("*" when empty) and per-target
	// variable flags. Every other provider refuses them.
	DestinationScope  string
	VariableProtected bool
	VariableHidden    bool
	VariableExpand    bool
	// KeySelection is resolved into KeyIDs before any ceremony (#157) and is
	// never stored.
	KeySelection *AdapterKeySelection
}

type AdapterTargetKey

type AdapterTargetKey = store.AdapterTargetKey

AdapterTargetKey intentionally shares a store-owned type with transport mapping. This sanctioned seam follows the system-architecture ADR; boundary_test.go enforces that handlers never import internal/store directly.

type AdapterTargetView

type AdapterTargetView struct {
	Target    store.AdapterTarget
	Conflicts []store.AdapterConflictArtifact
	Mapping   []adapter.ManifestEntry
	Workflow  string
}

type AdapterTeardownResult

type AdapterTeardownResult struct {
	Targets  []store.AdapterTeardownResult
	Orphaned []string
}

type AdapterView

type AdapterView struct {
	Adapter         store.AdapterRecord
	Targets         []AdapterTarget
	TargetConflicts map[string][]store.AdapterConflictArtifact
}

type Adapters

type Adapters struct {
	DB      *store.DB
	Auth    *Auth
	Keyring *crypto.Keyring
	// Budget applies the § 179 adapter sync/trigger concurrency bound (4 per
	// org). Nil disables it. The per-principal 10/min rate is deferred (see
	// budget.go).
	Budget        *Budget
	Now           func() time.Time
	ModuleFactory adapter.ModuleFactory
	// contains filtered or unexported fields
}

func (*Adapters) AddTarget

func (s *Adapters) AddTarget(ctx context.Context, actor Actor, scope domain.Scope, adapterID string, input AdapterTargetInput) (store.AdapterTarget, error)

func (*Adapters) Adopt

func (s *Adapters) Adopt(ctx context.Context, actor Actor, scope domain.Scope, request AdoptAdapterRequest) (AdoptAdapterResult, error)

func (*Adapters) ApplyTargetMutation

func (s *Adapters) ApplyTargetMutation(ctx context.Context, actor Actor, scope domain.Scope, request UpdateAdapterTargetRequest, keepRemote bool) (TargetMutationResult, error)

ApplyTargetMutation accepts requested target state and owns the update-versus- move decision. The decision and selected mutation share one write transaction, so a concurrent target mutation cannot bypass scrub-before-switch.

func (*Adapters) CancelMove

func (s *Adapters) CancelMove(ctx context.Context, actor Actor, scope domain.Scope, moveID string) (store.AdapterMove, error)

func (*Adapters) Create

func (s *Adapters) Create(ctx context.Context, actor Actor, scope domain.Scope, request CreateAdapterRequest) (AdapterView, error)

func (*Adapters) Delete

func (s *Adapters) Delete(ctx context.Context, actor Actor, scope domain.Scope, adapterID string, keepRemote bool) (AdapterTeardownResult, error)

func (*Adapters) Get

func (s *Adapters) Get(ctx context.Context, actor Actor, scope domain.Scope, adapterID string) (AdapterView, error)

func (*Adapters) InspectTarget

func (s *Adapters) InspectTarget(ctx context.Context, actor Actor, scope domain.Scope, targetID string) (AdapterTargetView, error)

func (*Adapters) List

func (s *Adapters) List(ctx context.Context, actor Actor, scope domain.Scope) ([]AdapterView, error)

func (*Adapters) Move

func (s *Adapters) Move(ctx context.Context, actor Actor, scope domain.Scope, moveID string) (store.AdapterMove, error)

func (*Adapters) MoveOrigin

func (s *Adapters) MoveOrigin(ctx context.Context, actor Actor, scope domain.Scope, adapterID, origin string, credential []byte, keepRemote bool) (store.AdapterRouteMoveBatch, error)

MoveOrigin keeps the old credential and origin authoritative through every target scrub. New credential remains sealed in the pending move and is used only by activation probes after old-route cleanup reaches terminal state.

func (*Adapters) PauseTarget

func (s *Adapters) PauseTarget(ctx context.Context, actor Actor, scope domain.Scope, targetID string) (store.AdapterTarget, error)

PauseTarget stops every push for one target (#157). It narrows what Hikyo does at the destination, so it carries manage-adapters alone and no reauthentication ceremony, exactly like credential revocation. The ledger is untouched: resume needs no re-adoption.

func (*Adapters) Plan

func (s *Adapters) Plan(ctx context.Context, actor Actor, scope domain.Scope, targetID string) (AdapterPlanResult, error)

func (*Adapters) RemoveTarget

func (s *Adapters) RemoveTarget(ctx context.Context, actor Actor, scope domain.Scope, targetID string, keepRemote bool) (AdapterTeardownResult, error)

func (*Adapters) ReplaceCredential

func (s *Adapters) ReplaceCredential(ctx context.Context, actor Actor, scope domain.Scope, adapterID string, credential []byte) (store.AdapterCredentialResult, error)

func (*Adapters) ResumeOriginMove

func (s *Adapters) ResumeOriginMove(ctx context.Context, actor Actor, scope domain.Scope, moveID, origin string, credential []byte) (store.AdapterMove, error)

func (*Adapters) ResumeTarget

func (s *Adapters) ResumeTarget(ctx context.Context, actor Actor, scope domain.Scope, targetID string) (store.AdapterResumeResult, error)

ResumeTarget lifts a pause and queues one catch-up converge (#157). It pushes again, so it carries the manual-sync formula and ceremony; the result names the published revision the converge reaches.

func (*Adapters) ResumeTargetMove

func (s *Adapters) ResumeTargetMove(ctx context.Context, actor Actor, scope domain.Scope, moveID string, request UpdateAdapterTargetRequest) (store.AdapterMove, error)

func (*Adapters) RevokeCredential

func (s *Adapters) RevokeCredential(ctx context.Context, actor Actor, scope domain.Scope, adapterID string) (store.AdapterCredentialResult, error)

func (*Adapters) SyncTarget

func (s *Adapters) SyncTarget(ctx context.Context, actor Actor, scope domain.Scope, targetID string) (store.AdapterEnqueueResult, error)

func (*Adapters) TestTarget

func (s *Adapters) TestTarget(ctx context.Context, actor Actor, scope domain.Scope, targetID string) (adapter.Connection, error)

type AdoptAdapterRequest

type AdoptAdapterRequest struct {
	TargetID              string
	ArtifactID            string
	ExpectedGeneration    int64
	ExpectedDestinationID int64
	ExpectedRepositoryID  int64
	Entries               []store.AdapterConflictEntry
}

type AdoptAdapterResult

type AdoptAdapterResult struct {
	Generation int64
	JobID      string
}

type Advisory

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

Advisory is the in-process fan-out. Under HA it remains per node, as fixed by ops-spec section 13; authorized polling supplies cross-node freshness.

func NewAdvisory

func NewAdvisory() *Advisory

NewAdvisory constructs the channel. A nil *Advisory is a working no-op, so a build that does not wire one simply has no live updates.

type AdvisoryEvent

type AdvisoryEvent struct {
	// Type identifies an environment advance, draft, changed cell, or topology.
	Type string
	// ProjectID is populated only for topology events, which disclose no
	// environment identity and remain authorizable after an environment deletes.
	ProjectID string
	// EnvironmentID is the object environment events are authorized against.
	EnvironmentID string
	KeyID         string
	KeyName       string
	// Revision is the environment's new revision, 0 on draft events.
	Revision int64
	// ActorID is the principal whose act produced the event, so the matrix can
	// distinguish "your pending change" from "someone else's".
	ActorID string
}

AdvisoryEvent is one metadata-only fact about a change.

type AffectedCredentialView

type AffectedCredentialView struct {
	ID               string
	ServiceAccountID string
	// ExpiresAt is the expiry the credential had BEFORE the clamp, so the
	// actor sees what they are shortening rather than what it becomes.
	ExpiresAt time.Time
	// Reason is one of the two closed values below. They are different
	// consequences and the operator is owed the difference.
	Reason AffectedReason
}

AffectedCredentialView names one credential a policy change touches.

type AffectedReason

type AffectedReason string

AffectedReason is why a policy change touches one credential.

const (
	// ReasonClamped is a finite credential beyond the new ceiling.
	ReasonClamped AffectedReason = "clamped"
	// ReasonIndefiniteWithdrawn is an indefinite credential the opt-in no
	// longer permits, which the confirmed change clamps to the ceiling.
	ReasonIndefiniteWithdrawn AffectedReason = "indefinite-withdrawn"
)

type ApplyOptions

type ApplyOptions struct {
	AllowDelete bool
	Digest      string
	Commit      string
	Ref         string
	Actor       string
	// Acknowledgements are the secret-scanning override tokens a skew re-scan
	// honors (#74 SS3, ADR §7 (c)). They are consumed only when apply re-scans —
	// i.e. the running ruleset snapshot differs from the plan's; a same-version
	// apply runs no scan and ignores them.
	Acknowledgements []string
	// ConfirmWidening names the people this apply's key folder moves give
	// access to through their member access rules (ADR D9), across every moved
	// key. A widening apply commits only when it names exactly that set.
	ConfirmWidening []domain.PrincipalID
}

ApplyOptions carries the apply request fields.

type ApplyResult

type ApplyResult struct {
	Revision  int64
	Published []string
	PlanID    string
}

ApplyResult is the apply response.

type ApprovalApproverSpec

type ApprovalApproverSpec struct {
	Kind      string // "principal" | "scim_group"
	SubjectID string
	BindingID string // SCIM binding, for a group approver
}

ApprovalApproverSpec is one approver-set member as the admin surface states it.

type ApprovalBypass

type ApprovalBypass struct {
	Reason string
}

ApprovalBypass carries an emergency bypasser's mandatory reason (#151).

type ApprovalCeremonyBinding

type ApprovalCeremonyBinding struct {
	KeyIDs []string
	Window RevealWindow
}

ApprovalCeremonyBinding is the approval-authorized preflight used by clients that hold publish without read. It carries no value material.

type ApprovalPolicyInput

type ApprovalPolicyInput struct {
	EnvironmentID     string // "" = all environments in the project
	MinApprovals      int
	AllowSelfApproval bool
	RequestTTLSeconds int
	Enabled           bool
	Approvers         []ApprovalApproverSpec
	Bypassers         []string // principal ids
}

ApprovalPolicyInput is a policy create/update request from the admin surface.

type ApprovalPolicyView

type ApprovalPolicyView struct {
	PrincipalNames    map[string]string
	ID                string
	EnvironmentID     string
	MinApprovals      int
	AllowSelfApproval bool
	RequestTTLSeconds int
	Enabled           bool
	Version           int64
	Approvers         []ApprovalApproverSpec
	Bypassers         []string
	CreatedAt         time.Time
	UpdatedAt         time.Time
}

ApprovalPolicyView is a policy as the admin surface reads it.

type ApprovalRequestSummary

type ApprovalRequestSummary struct {
	ID            string
	EnvironmentID string
	PolicyID      string
	State         string
	ExpiresAt     time.Time
}

ApprovalRequestSummary is the created-request summary a gated publish returns.

type ApprovalRequestView

type ApprovalRequestView struct {
	RequesterName    string
	ID               string
	EnvironmentID    string
	PolicyID         string
	PolicyVersion    int64
	Requester        string
	ChangeCount      int
	BaseRevision     int64
	Purpose          string
	State            string
	InvalidatedCause string
	CreatedAt        time.Time
	ExpiresAt        time.Time
	ResolvedAt       *time.Time
	MinApprovals     int
	Approvals        int
	KeyIDs           []string
	Votes            []ApprovalVoteView
}

ApprovalRequestView is a request as the review surface reads it.

type ApprovalVoteView

type ApprovalVoteView struct {
	PrincipalName string
	PrincipalID   string
	Decision      string
	CreatedAt     time.Time
}

ApprovalVoteView is one recorded vote.

type Approvals

type Approvals struct {
	DB   *store.DB
	Auth *Auth
	// Keyring recomputes the publish preview token when creating and merging a
	// request, so the pinned digest is derived exactly as the publish path
	// derives it. Nil is a wiring fault.
	Keyring *crypto.Keyring
	Now     func() time.Time
}

Approvals is the change-approval service.

func (*Approvals) CeremonyBinding

func (s *Approvals) CeremonyBinding(ctx context.Context, actor Actor, scope domain.Scope, requestID string) (ApprovalCeremonyBinding, error)

CeremonyBinding returns the exact key unit and window policy for a named approval decision. It is authorized by publish, matching vote, merge, and bypass, so clients never need read or reveal merely to prepare the ceremony.

func (*Approvals) CreatePolicy

func (s *Approvals) CreatePolicy(ctx context.Context, actor Actor, scope domain.Scope, input ApprovalPolicyInput) (ApprovalPolicyView, error)

CreatePolicy adds a scoped policy. Project-scoped authority.

func (*Approvals) DeletePolicy

func (s *Approvals) DeletePolicy(ctx context.Context, actor Actor, scope domain.Scope, id string) error

DeletePolicy removes a policy and its member sets (FK cascade). Open requests pinned to it fail closed at merge/vote via the missing-coverage check.

func (*Approvals) ExpireDue

func (s *Approvals) ExpireDue(ctx context.Context) error

ExpireDue is one bounded scheduler batch. It resolves up to 100 active requests past expiry and emits a per-request event under scoped scheduler authority. Repeated calls drain a backlog with committed progress. Under HA, tx.WriteResult validates the scheduler context's lease in this transaction, fencing expiry and its audit event together against stale leadership terms.

func (*Approvals) ListPolicies

func (s *Approvals) ListPolicies(ctx context.Context, actor Actor, scope domain.Scope) ([]ApprovalPolicyView, error)

ListPolicies returns the project's policies. Project-scoped read.

func (*Approvals) ListRequests

func (s *Approvals) ListRequests(ctx context.Context, actor Actor, scope domain.Scope) ([]ApprovalRequestView, error)

ListRequests returns an environment's approval requests with their votes.

func (*Approvals) OperationalCounts

func (s *Approvals) OperationalCounts(ctx context.Context) (active, expired int64, err error)

OperationalCounts returns the installation-wide active/expired request counts for the label-free /metrics gauges, read under scheduler authority. Best effort: a scrape reads it and reports zeros on error rather than failing.

func (*Approvals) UpdatePolicy

func (s *Approvals) UpdatePolicy(ctx context.Context, actor Actor, scope domain.Scope, id string, input ApprovalPolicyInput) (ApprovalPolicyView, error)

UpdatePolicy replaces a policy's fields and member sets, bumping its version (which fails every request pinned to the old version closed at merge/vote).

func (*Approvals) Vote

func (s *Approvals) Vote(ctx context.Context, actor Actor, scope domain.Scope, requestID, decisionRaw string) (ApprovalRequestView, error)

Vote records one approver's decision. It re-authorises the voter as a currently-eligible approver, refuses self-approval unless the policy permits it, is idempotent on a repeated identical decision and a 409 on a conflicting one, and consumes a purpose-bound reauthentication ceremony first.

type Artifact

type Artifact string

Artifact is a session artifact kind: the closed set of client classes this instance mints sessions for. It is a type rather than a bare string because it threads through login, minting and the audit trail, and each of those is a place a typo would otherwise become a silently different session class — a browser session with the CLI's lifetime, say, or a cookie leg with no CSRF contract.

const (
	// ArtifactCLI is a terminal session: a replayable bearer token, no cookie
	// channel, and therefore no CSRF contract.
	ArtifactCLI Artifact = "cli"
	// ArtifactBrowser is a cookie session: HttpOnly token, shorter clocks, and
	// a synchronizer token the client must echo.
	ArtifactBrowser Artifact = "browser"
)

func (Artifact) String

func (a Artifact) String() string

func (Artifact) Valid

func (a Artifact) Valid() bool

Valid reports whether a names a kind this instance mints. The wire enum is closed, so anything else is a caller error rather than a future value.

type Assurance

type Assurance struct {
	Method          string
	Provider        string
	Factors         []string
	AuthenticatedAt time.Time
	CeremonyID      string
}

Assurance and Identity are the service layer's own shapes for what the chokepoint resolved. They are restated here rather than re-exported from internal/authz because the transport must not import the authorization package at all - the boundary test enforces that edge, and it is what keeps "handlers extract artifacts, they never evaluate policy" structural.

type AuditEvent

type AuditEvent = store.AuditEvent

AuditEvent is one stored trail row, re-exported for the transport.

type AuditFilter

type AuditFilter = store.AuditFilter

AuditFilter and AuditEvent are the store's own types, re-exported so the transport layer names them through this package instead of importing the datastore directly (the internal/server -> internal/store boundary; the same alias seam the adapter surface uses). The store owns the shape; the handler builds the filter and renders the event without reaching past the service.

type AuditPage

type AuditPage struct {
	ActorNames map[string]string
	Events     []store.AuditEvent
	NextSeq    int64
	UpperSeq   int64 // the session ceiling pinned for this paging run; echo it to resume
	Exhausted  bool
}

AuditPage is one interactive query response. Events are the rows that matched the filter's equality fields; NextSeq is the resume cursor for the next request; Exhausted is true when the trail has no more rows within the pinned window. The service fills the page (fillPage) — a selective filter no longer returns a near-empty page just because the underlying store read was sparse; it keeps reading until Events reaches the page limit or the trail ends. Events can still be short with Exhausted=false only when a per-request scan budget is spent (fillPage), in which case the caller resumes at NextSeq.

type Audits

type Audits struct {
	DB *store.DB
	// Budget applies the ops-spec § 179 / § 20 expensive-path budget to exports:
	// 5/min per principal, 2 concurrent per org, 6 per instance. Nil disables it.
	Budget *Budget
}

Audits is the audit trail's read surface (#45, audit-model ADR § Storage and export). Reading the trail is itself audited, unconditionally: a query commits its own event in the same transaction as the page read (durable before the response); an export takes the INTENT/OUTCOME pair with every page read in its own transaction under a fresh proof.

func (*Audits) Export

func (s *Audits) Export(ctx context.Context, principal domain.PrincipalID, scope domain.Scope, f store.AuditFilter, pageSize int, w io.Writer) error

Export streams the addressed slice of the tenant trail as JSONL: export_started durable BEFORE the first byte; each page read in its own transaction under a fresh proof (revoking audit-read stops the stream at the next page boundary); only committed page data is emitted; a terminal export_completed on success, page failure and sink disconnect. pageSize bounds each page read (the ops spec owns defaults).

func (*Audits) ExportActor

func (s *Audits) ExportActor(ctx context.Context, actor Actor, scope domain.Scope, f store.AuditFilter, pageSize int, w io.Writer) (ExportReceipt, error)

ExportActor re-resolves the bearer and its assurance at every page boundary.

func (*Audits) InstanceExport

func (s *Audits) InstanceExport(ctx context.Context, principal domain.PrincipalID, f store.AuditFilter, pageSize int, w io.Writer) error

InstanceExport is Export for the instance trail.

func (*Audits) InstanceExportActor

func (s *Audits) InstanceExportActor(ctx context.Context, actor Actor, f store.AuditFilter, pageSize int, w io.Writer) error

InstanceExportActor is InstanceExport with transaction-local bearer resolution.

func (*Audits) InstanceExportActorReceipt

func (s *Audits) InstanceExportActorReceipt(ctx context.Context, actor Actor, f store.AuditFilter, pageSize int, w io.Writer) (ExportReceipt, error)

InstanceExportActorReceipt is the instance route's completion-protocol seam. It uses exactly the same receipt, paging and authorization owner as tenant exports.

func (*Audits) InstanceQuery

func (s *Audits) InstanceQuery(ctx context.Context, principal domain.PrincipalID, f store.AuditFilter) (AuditPage, error)

InstanceQuery is Query for the instance trail, under an instance-scope audit-read grant — grant-evaluated, never route-implied.

func (*Audits) InstanceQueryActor

func (s *Audits) InstanceQueryActor(ctx context.Context, actor Actor, f store.AuditFilter) (AuditPage, error)

InstanceQueryActor is InstanceQuery with transaction-local bearer resolution.

func (*Audits) Query

func (s *Audits) Query(ctx context.Context, principal domain.PrincipalID, scope domain.Scope, f store.AuditFilter) (AuditPage, error)

Query returns one bounded page of the tenant trail addressed by scope. The page is materialized, the query event inserted, and both commit in one transaction — the event is durable before any byte of the response exists outside it.

Interactive pages are ordered by the allocation seq. A transaction that commits out of allocation order can land below a cursor that already passed it, so that event can be absent from the remainder of one paging session; it is durable and a fresh query recovers it. Export is the gap-free surface: it pages in commit order behind the writer barrier.

func (*Audits) QueryActor

func (s *Audits) QueryActor(ctx context.Context, actor Actor, scope domain.Scope, f store.AuditFilter) (AuditPage, error)

QueryActor resolves a network caller inside the same transaction that reads and records the audit page, preserving session assurance and revocation.

type Auth

type Auth struct {
	// OAuth2HTTPClient is a test transport seam; production uses bounded federation HTTP.
	OAuth2HTTPClient *http.Client
	// SelfConfig is the setup coordinator, wired by both server and host admin
	// composition roots. Its provisioning shares the first-admin transaction.
	SelfConfig *SelfConfig
	DB         *store.DB
	Keyring    *crypto.Keyring
	// KDF is the instance's configured Argon2id cost. Boot has already
	// verified it against the floor; this is the value new verifiers use.
	KDF crypto.PasswordParams
	// Admission is the instance-wide pre-authentication budget. Every path
	// that can run Argon2id — including the dummy-verifier path — passes
	// through it, or the budget is decorative.
	Admission *admission.Limiter
	// Now is injectable for tests; nil means time.Now.
	Now func() time.Time
	// ExternalOrigin is the instance's public origin; the OIDC callback validates
	// the redirect it replays against the per-provider registered URI (A1).
	ExternalOrigin   string
	FederationPolicy federationhttp.Policy
	// OIDCDiscover replaces go-oidc discovery in tests, so a fixture can point an
	// httptest IdP's discovery at a byte-variant issuer. Nil means oidcrp.Discover.
	OIDCDiscover func(ctx context.Context, issuer string) (*oidcrp.Provider, error)
	// WebAuthn is the relying party: RP ID + expected origins are immutable
	// instance config derived from ExternalOrigin, never a request header (§5).
	// Nil means WebAuthn routes refuse (the RP could not be configured at boot).
	WebAuthn *webauthnrp.RP
	// ReauthWindow is the effective reauthentication window (default 0). OIDC
	// reauth opens a window only where it is > 0; a 0-window gate needs WebAuthn
	// (finding B18). #55's project-settings knob sets it per environment.
	ReauthWindow time.Duration
	// ReauthHardCap bounds the absolute age of a reauth window, never extended by
	// activity. Zero means the idle window value.
	ReauthHardCap time.Duration
	// Log records server-side faults that must not reach the caller — an
	// unreadable verifier answers the uniform refusal, and the reason it was
	// unreadable belongs in the process log and nowhere else.
	Log *slog.Logger

	// SecondFactorRequired is the instance's second-factor policy (#760): true
	// when HIKYO_SECOND_FACTOR is `required`, so a password login on an account
	// with no factor mints a session confined to enrolment. The composition root
	// wires it from config; the isolation harness leaves it false (optional),
	// today's local floor.
	SecondFactorRequired bool

	MailFailed func()
	// contains filtered or unexported fields
}

Auth is the human-authentication service.

func (*Auth) ApplyPrivacySubject

func (s *Auth) ApplyPrivacySubject(ctx context.Context, principal, action, expectedAccount string) (PrivacyReceipt, error)

ApplyPrivacySubject permanently restricts login/authorization. Erasure also destroys authentication custody and replaces direct identity with a tombstone. expectedAccount is required when reapplying a receipt, preventing an accidental receipt/target mismatch. Empty expectedAccount is the first local application.

func (*Auth) ApproveCLILogin

func (s *Auth) ApproveCLILogin(ctx context.Context, actor Actor, reference string) (CLIReauthApproval, error)

func (*Auth) ApproveCLIReauth

func (s *Auth) ApproveCLIReauth(ctx context.Context, actor Actor, state string) (CLIReauthApproval, error)

func (*Auth) AuthMethods

func (s *Auth) AuthMethods(ctx context.Context) ([]AuthMethodProvider, bool, error)

AuthMethods returns enabled OIDC and SAML providers and reports local login enabled. OIDC brands are derived from the pinned issuer. This is proof-free, instance-level discovery; repository read errors propagate.

func (*Auth) BootstrapAdmin

func (s *Auth) BootstrapAdmin(ctx context.Context, username, displayName, delivery string) (BootstrapResult, error)

BootstrapAdmin creates the first administrator and mints its credential-establishment authority.

The authority is what resolves the otherwise-circular requirement that a credential predate every enrolment: it establishes the first administrator's initial credential and nothing else, granting no session and no assurance.

delivery names how the caller will hand the value over, and is recorded in the audit event because delivery mode IS the security property — a value that reached a log shipper is a different event from one written to a root-owned file.

func (*Auth) BreakGlassResetCredential

func (s *Auth) BreakGlassResetCredential(ctx context.Context, targetPrincipal, delivery string) (ResetResult, error)

BreakGlassResetCredential is the host-local tier: `hikyo admin reset-credential`. It runs on the server's own host under local authority (root key + host access resolved by the caller before this runs), reaches no chokepoint operation, and is the ONLY path permitted to reset a target regardless of the org-bounded predicate — including an instance-capability holder. There is deliberately NO network route; the classification-totality invariant keeps it that way.

func (*Auth) CLILoginTransaction

func (s *Auth) CLILoginTransaction(ctx context.Context, actor Actor, reference string) (CLILoginTransaction, error)

func (*Auth) CLIReauthTransaction

func (s *Auth) CLIReauthTransaction(ctx context.Context, actor Actor, state string) (CLIReauthTransaction, error)

func (*Auth) CheckPasswordConfiguration

func (s *Auth) CheckPasswordConfiguration(ctx context.Context) error

CheckPasswordConfiguration prevents a new serving configuration from making existing passwords unusable. Public verification retains one admitted cost for known and unknown accounts. Restored, superseded credentials are inert already and are not a reason to reject the operator's recovery configuration.

func (*Auth) ConfigureWebAuthnRP

func (s *Auth) ConfigureWebAuthnRP() error

ConfigureWebAuthnRP builds the relying party from ExternalOrigin (RP ID = host, expected origin = the origin verbatim) and installs it. Boot and tests call it so the RP config has exactly one derivation; an origin that yields no valid RP is an error the caller refuses on.

func (*Auth) ConsumeAdapterReauthWindow

func (s *Auth) ConsumeAdapterReauthWindow(ctx context.Context, az *authz.TxAuthorizer, sessionID, environmentID string,
	intent ReauthIntent, now time.Time) error

ConsumeAdapterReauthWindow consumes one environment's share of an adapter ceremony. Every share is bound to the same full environment set, purpose and operation, so independently consumed per-environment windows cannot be mixed across adapter acts or assembled from partial ceremonies.

func (*Auth) ConsumeDeveloperCredentialReauth

func (s *Auth) ConsumeDeveloperCredentialReauth(ctx context.Context, az *authz.TxAuthorizer, caller authz.Identity, intent ReauthIntent, now time.Time) error

func (*Auth) ConsumeReauthEvidence

func (s *Auth) ConsumeReauthEvidence(ctx context.Context, az *authz.TxAuthorizer, ev ReauthEvidence, caller domain.PrincipalID) error

ConsumeReauthEvidence spends the proof inside the caller's transaction. It fails closed on a replayed TOTP step and on evidence belonging to a different principal than the one this transaction authenticated.

func (*Auth) ConsumeReauthWindow

func (s *Auth) ConsumeReauthWindow(ctx context.Context, az *authz.TxAuthorizer, sessionID string,
	intent ReauthIntent, now time.Time) error

ConsumeReauthWindow is the disclosure-time half of the reauthentication gate. It runs inside the disclosure's own transaction; the future reveal path calls it before disclosing the enumerated keys in one environment.

A disclosure on environment E requires a live window for (session, E): now < hard_expires_at AND now < window_expires_at, at the current credential epoch. A single_decision window — opened by a 0-window WebAuthn ceremony bound to an enumerated unit — authorizes exactly the unit its ceremony pinned and is consumed by exactly one decision through the consumed_at NULL guard. A sliding window slides window_expires_at forward per disclosure, never past the hard cap.

`operation` names the operation this disclosure is being authorized for. A window carrying an EXACT BINDING — today, one opened by a workspace step-up, where the human consented to one named operation over one named key set — authorizes that pair and refuses everything else. An UNBOUND window (every #54 opener: TOTP, OIDC, WebAuthn) keeps the environment-wide semantics it was designed with. The asymmetry is the point: a consent that named an operation must not become a consent for whatever the holder asks next.

func (*Auth) ConsumeRecoveryCode

func (s *Auth) ConsumeRecoveryCode(ctx context.Context, username, code string) (RecoveryResult, error)

ConsumeRecoveryCode is the pre-auth break-in-glass path. It rides the admission budget and answers uniformly: an unknown username, an absent batch, a stale epoch and a non-matching code all cost a set scan and refuse identically. On a match it removes that code (CAS on the batch), sweeps the account's outstanding authorities (finding B12), mints a recovery-issued credential-establishment authority (which may only ever establish a password, enforced by the DB CHECK), advances the generation and deletes every session — all in one transaction. A losing CAS discards the authority (finding B22).

func (*Auth) ConsumeSelfConfigReauth

func (s *Auth) ConsumeSelfConfigReauth(ctx context.Context, az *authz.TxAuthorizer, caller authz.Identity, intent ReauthIntent, now time.Time) error

ConsumeSelfConfigReauth spends only a fresh, exact single-decision window in the action's final transaction. It cannot consume disclosure or sliding gates.

func (*Auth) CorrectPrivacySubject

func (s *Auth) CorrectPrivacySubject(ctx context.Context, principal, username, displayName string) (PrivacyReceipt, error)

CorrectPrivacySubject rectifies local account labels without changing identity provider subject keys. All sessions are revoked so clients refresh identity.

func (*Auth) EnableLocalSignup

func (s *Auth) EnableLocalSignup(capture func(context.Context) (*runtimeconfig.Bundle, error))

func (*Auth) EnableSignup

func (s *Auth) EnableSignup(registration *Registration, budget *Budget) error

EnableSignup wires the federated sign-up leg. Both halves are required: a policy without a budget would admit sign-ups unbudgeted (fail-open), so a nil budget is refused here, at construction, not discovered at a callback.

func (*Auth) EnrolPasskeyFinish

func (s *Auth) EnrolPasskeyFinish(ctx context.Context, presented string, responseJSON []byte) (LoginResult, error)

EnrolPasskeyFinish validates the registration response, records residency from credProps (absent credProps => non-discoverable, fail-closed on the login capability, B13), and completes the account-security mutation: it creates the credential and reissues the acting session from the proof ceremony (never the new passkey, B1/B3), asserting the passkey-only invariant in the same tx.

func (*Auth) EnrolPasskeyStart

func (s *Auth) EnrolPasskeyStart(ctx context.Context, presented, password, code string) ([]byte, error)

EnrolPasskeyStart verifies the account-security proof possession-first (the confirmed TOTP code where one stands, else the pre-existing password; never the passkey being added, B7/B1) and stages an enrolment ceremony bound to the acting session, recording the proof class so the finish can reissue the session solely from it (B3). The proof is SPENT in the same write transaction that creates the ceremony: a TOTP step is advanced under CAS there, so a replay of the same code cannot open a second ceremony, and a password proof is re-checked against the live row and epoch. It returns the credential-creation options once.

func (*Auth) EnrolTOTPConfirm

func (s *Auth) EnrolTOTPConfirm(ctx context.Context, presented, code string) (LoginResult, error)

EnrolTOTPConfirm consumes a valid code against the pending seed and completes the enrolment as an account-security mutation: the pending row is promoted (CAS on its step, so the confirming code is single-use like every other), then the generation advances, every session is deleted, and the acting session is reissued carrying ONLY the proof class (password) — NOT totp. The user steps up separately to present the factor they just enrolled (B2/B3).

func (*Auth) EnrolTOTPStart

func (s *Auth) EnrolTOTPStart(ctx context.Context, presented, password string) (string, error)

EnrolTOTPStart verifies the account-security proof (the pre-existing password, since no possession factor stands yet), stages a fresh sealed seed as a pending enrolment, and returns the otpauth URI ONCE. It performs no account-security mutation — the pending row is inert and proves nothing until EnrolTOTPConfirm completes it — so it advances no generation and reissues no session (finding B2).

func (*Auth) EstablishCredential

func (s *Auth) EstablishCredential(ctx context.Context, authority, password string) error

EstablishCredential consumes a credential-establishment authority and sets exactly one initial credential, atomically, and nothing more: no session is created, no assurance is carried, no reauthentication window opens. The holder authenticates afterwards with the credential they just set.

Every refusal — unknown, expired, consumed, wrong epoch — answers domain.ErrUnauthenticated, so presentation reveals nothing about which authorities exist. A weak password is the one loud refusal: it is the caller's own input, evaluated before anything is looked up.

func (*Auth) ExportPrivacySubject

func (s *Auth) ExportPrivacySubject(ctx context.Context, principal string) (PrivacyExport, error)

ExportPrivacySubject is reachable only under local host authority. It reads explicit subject predicates and cannot disclose stored values or verifiers.

func (*Auth) GenerateRecoveryCodes

func (s *Auth) GenerateRecoveryCodes(ctx context.Context, presented, proof string) ([]string, LoginResult, error)

GenerateRecoveryCodes replaces the account's recovery batch as an account-security mutation and returns the plaintext codes ONCE. The proof is the confirmed TOTP code where one stands, else the password (finding B7); recovery codes never authorize their own regeneration. The batch is a sealed JSON array of the codes' verifiers; only the verifiers persist.

func (*Auth) Identity

func (s *Auth) Identity(ctx context.Context, presented string) (Identity, error)

Identity resolves a presented session artifact. It is the read half of every authenticated request, and it runs in the request's own transaction at the chokepoint — never in a middleware, never cached.

func (*Auth) ListIdentities

func (s *Auth) ListIdentities(ctx context.Context, presented string) ([]ExternalIdentityView, error)

ListIdentities returns an account's linked external identities.

func (*Auth) ListPasskeys

func (s *Auth) ListPasskeys(ctx context.Context, presented string) ([]PasskeyView, error)

ListPasskeys lists the acting account's enrolled credentials.

func (*Auth) LocalLogin

func (s *Auth) LocalLogin(ctx context.Context, username, password string, artifact Artifact) (LoginResult, error)

LocalLogin is the local floor: password verification against an envelope-encrypted Argon2id verifier, minting the session artifact the caller asked for — a CLI session, or the browser session #56's login page establishes.

The shape is dictated by the enumeration rule. An unknown account traverses the same admission budget, the same per-account backoff bucket and a bounded dummy-verifier derivation, so neither the response nor the timing distinguishes it from a wrong password on a real account. Credential refusals answer domain.ErrUnauthenticated. A verified password on an enrolled account requesting a CLI artifact instead receives browser sign-in guidance.

func (*Auth) LoginChallengeTOTP

func (s *Auth) LoginChallengeTOTP(ctx context.Context, challengeID, code string) (LoginResult, error)

LoginChallengeTOTP satisfies a login challenge with a TOTP code and mints a browser session recording [password, totp]. It mirrors StepUpTOTP's verify discipline (admission budget, sealed-seed validation, single-use step CAS) but mints a new session instead of rotating one, and additionally consumes the challenge single-use. A wrong code leaves the challenge usable for a retry; a replayed step is the loud already-used conflict.

func (*Auth) LoginChallengeWebauthnFinish

func (s *Auth) LoginChallengeWebauthnFinish(ctx context.Context, challengeID string, responseJSON []byte) (LoginResult, error)

LoginChallengeWebauthnFinish verifies an account-bound assertion against a live login challenge and mints a browser session recording [password, webauthn]. It mirrors PasskeyLoginFinish's sign-count/clone rule, but the account is KNOWN from the challenge (the assertion is bound to that account, not discoverable), and it consumes the login challenge single-use in the same write transaction.

func (*Auth) LoginChallengeWebauthnStart

func (s *Auth) LoginChallengeWebauthnStart(ctx context.Context, challengeID string) ([]byte, error)

LoginChallengeWebauthnStart opens a WebAuthn assertion ceremony scoped to the challenge's account, so the passkey is bound to THAT account rather than being discoverable. It carries the `login-2fa` purpose (the `login` purpose already means discoverable login) and is session-less. The challenge is not consumed here — only the finish op consumes it.

func (*Auth) Logout

func (s *Auth) Logout(ctx context.Context, presented string) error

Logout revokes the presented session. A session that no longer resolves answers the uniform unauthenticated refusal: there is nothing to revoke and nothing to report.

func (*Auth) LowerEffectiveWindow

func (s *Auth) LowerEffectiveWindow(ctx context.Context, az *authz.TxAuthorizer, envID string, newValue time.Duration) ([]domain.PrincipalID, int, error)

LowerEffectiveWindow performs, in one transaction, the five ADR items on an environment's effective-window transition to newValue (human-auth ADR - Reauthentication; finding B6). It is the library #55's project-settings knob calls; this vertical ships it plus a fixture, with #55 named as the caller.

The five items: (1) invalidate every open window on the environment; (2) RETAIN grants — a settings change never revokes a capability; (3) enumerate the principals a 0 effective window strands (reveal/reveal-history there without an enrolled WebAuthn authenticator) and return them so the caller can surface them before commit; (4) disclosure fails closed for them until they enrol — a consequence of the invalidation plus the 0-window rule, not a separate write; (5) factor enrolment stays reachable — it is an account-security mutation, never gated by the reveal window, so nothing to do. The audit event carries the stranded list.

Stranded principals are computed only when newValue <= 0: at a smaller non-zero window TOTP still opens a window, so no reveal holder is locked out.

newValue is the SAME per-environment quantity effectiveReauthWindow resolves for the window openers — this is the writer, that is the reader, one value — so once #55 persists per-environment overrides, a lowering here is what ReauthTOTP/OIDC read there; they cannot diverge onto the global window (A2).

func (*Auth) MyProfile

func (s *Auth) MyProfile(ctx context.Context, presented string) (AccountProfile, error)

MyProfile reads the authenticated account's editable names and read-only email.

func (*Auth) OAuth2Callback

func (s *Auth) OAuth2Callback(ctx context.Context, slug, code, stateValue, issParam, idpError, bindingCookie, presented string) (OIDCCallbackResult, error)

func (*Auth) OAuth2Start

func (s *Auth) OAuth2Start(ctx context.Context, slug, purpose, intent, signupOrg, environmentID, presented, proof string, browser bool) (OIDCStartResult, error)

func (*Auth) OIDCCallback

func (s *Auth) OIDCCallback(ctx context.Context, slug, code, stateValue, issParam, idpError, bindingCookie, presented string) (OIDCCallbackResult, error)

OIDCCallback processes an IdP redirect against its own transaction. Mix-up is refused BEFORE any token is fetched (A1): the callback's provider slug must equal the transaction's provider, and the RFC 9207 iss (when present) must equal the pinned issuer. The transaction is consumed single-use; the exchange runs only at the recorded provider; the ID token is validated completely; and the purpose wall is structural - the branch is the transaction's purpose.

func (*Auth) OIDCStart

func (s *Auth) OIDCStart(ctx context.Context, slug, purpose, intent, signupOrg, environmentID, presented, proof string, browser bool) (OIDCStartResult, error)

OIDCStart creates a single-use transaction and returns the IdP authorization URL. login is anonymous and browser-cookie-bound; link and reauth require an authenticated session and are session-bound, and link additionally verifies the account-security proof (the pre-existing password) up front, binding it to the transaction ceremony (A6). claim (#610) is anonymous and browser-cookie-bound too: its proof is a credential-establishment authority, checked without consumption and recorded on the transaction, and a refused authority is audited by cause before any round-trip. PKCE S256 is always used.

A login records its intent (#604 d1, d2; absent = sign-in) and, for a sign-up, the addressed scope (signupOrg, absent = instance). Intent on any other purpose, and a scope without sign-up, refuse uniformly in the ErrBadPurpose shape. The start reads no registration policy (#604 d5). Reauth without an assurance policy returns ErrReauthNoPolicy before redirect; admission, authentication and transaction-write errors propagate, while a discovery failure returns ErrProviderDiscovery.

func (*Auth) PasskeyLoginFinish

func (s *Auth) PasskeyLoginFinish(ctx context.Context, responseJSON []byte) (LoginResult, error)

PasskeyLoginFinish validates a discoverable assertion, applies the B9 sign-count rule (a real clone disables the credential and sweeps its sessions before refusing), and mints a browser session carrying webauthn assurance in one gesture (method local-passkey, factors [webauthn]).

func (*Auth) PasskeyLoginStart

func (s *Auth) PasskeyLoginStart(ctx context.Context) ([]byte, error)

PasskeyLoginStart opens a discoverable-credential login ceremony. It is pre-auth: no account is named (the authenticator selects the credential), so the ceremony carries no account or session.

func (*Auth) PollCLIDevice

func (s *Auth) PollCLIDevice(ctx context.Context, code string) (CLIDeviceAttempt, error)

func (*Auth) ReapSignups

func (s *Auth) ReapSignups(ctx context.Context) error

ReapSignups prunes only expired pending rows, atomically with their trail events.

func (*Auth) ReapplyPrivacyReceipt

func (s *Auth) ReapplyPrivacyReceipt(ctx context.Context, receipt PrivacyReceipt) (PrivacyReceipt, error)

ReapplyPrivacyReceipt checks the source instance before any mutation. The caller must keep the restored server isolated until all receipts are replayed.

func (*Auth) ReauthAdapterTOTP

func (s *Auth) ReauthAdapterTOTP(ctx context.Context, presented string, intent ReauthIntent, code string) ([]ReauthResult, error)

ReauthAdapterTOTP proves one adapter ceremony with one TOTP code and opens one purpose-bound window for every environment in the full set whose effective window is non-zero. Effective-zero environments are deliberately omitted: each needs its own signed WebAuthn assertion, but every resulting window is still bound to this exact full environment set.

func (*Auth) ReauthPasskeyFinish

func (s *Auth) ReauthPasskeyFinish(ctx context.Context, presented string, responseJSON []byte) (ReauthResult, error)

ReauthPasskeyFinish validates the assertion and opens a reauthentication window over the bound environment. Where the effective window is 0 the window is single-decision (B11); otherwise it slides by the configured window.

func (*Auth) ReauthPasskeyStart

func (s *Auth) ReauthPasskeyStart(ctx context.Context, presented string, intent ReauthIntent) ([]byte, error)

ReauthPasskeyStart opens a reauth ceremony bound to the enumerated unit (purpose + environment + sorted key ids), so the challenge authorizes exactly that decision and no other with the same shape.

func (*Auth) ReauthTOTP

func (s *Auth) ReauthTOTP(ctx context.Context, presented string, intent ReauthIntent, code string) (ReauthResult, error)

ReauthTOTP opens a reauthentication window over one environment by presenting a TOTP code, the possession-factor analog of OIDC reauth. Like OIDC, TOTP cannot bind the challenge to the enumerated unit, so it opens a window only where the effective window is > 0 and refuses at a 0 window naming the remedy (a WebAuthn ceremony); only WebAuthn opens a single-decision 0-window gate.

It ships as a service method exercised by fixtures: the HTTP endpoint the design lists (POST /auth/reauth/totp) waits on the reveal surface (#50/#58), since there is no disclosure yet for a TOTP window to gate.

func (*Auth) RedeemCLILogin

func (s *Auth) RedeemCLILogin(ctx context.Context, code, verifier, redirect string) (LoginResult, error)

func (*Auth) RedeemCLIReauth

func (s *Auth) RedeemCLIReauth(ctx context.Context, code, pkceVerifier string) (CLIReauthRedeemed, error)

func (*Auth) RemovePasskey

func (s *Auth) RemovePasskey(ctx context.Context, presented, credentialID, password, code string) (LoginResult, error)

RemovePasskey removes a credential as an account-security mutation. The passkey-only invariant is checked on the POST-removal state first, so an impossible removal (the second-to-last discoverable authenticator of a passwordless account) is refused structurally before any proof is asked for. A valid removal is then proven possession-first by a pre-existing credential (the confirmed TOTP code where one stands, else the password; never the credential being removed, B7), the proof spent inside the removal's own write transaction, and the acting session reissued from that proof alone.

func (*Auth) RemoveTOTP

func (s *Auth) RemoveTOTP(ctx context.Context, presented, password string) (LoginResult, error)

RemoveTOTP removes the confirmed factor. The mutated credential is excluded from the proof set (finding B7), so with no OTHER possession factor the proof is the password — a stolen phone alone cannot drop the very factor it is (never accept the factor being removed to authorize its own removal). It reissues the acting session carrying only the password class.

func (*Auth) RequireDisclosureAuthority

func (s *Auth) RequireDisclosureAuthority(
	ctx context.Context, az *authz.TxAuthorizer, caller authz.Identity,
	actorGrants []authz.GrantRow, project domain.Scope, current, historical []domain.EnvID,
	now time.Time,
) error

RequireDisclosureAuthority is the shared conjunct of the MINT row and the WIDEN row of the machine-identities ADR's authorization table: over the environments handed to it, the actor must hold the matching disclosure capability AND a live reauthentication window.

It lives on *Auth because the reauthentication half is *Auth's machinery and the two callers — the credential mint and the grant surface's widening gate — must not be able to disagree about what the conjunct means.

The two environment sets stay separate all the way down. Accepting `reveal` over an environment where only HISTORICAL plaintext became reachable would be the collapse the ADR names as a bypass, one function later than where it was designed out.

The reauthentication conjunct ranges over exactly the environments the disclosure conjunct ranged over, and over nothing when that set is empty. That is not a loophole: the ADR gates "every operation that creates, replaces, or expands a working path from a machine credential to plaintext", and an operation reaching no plaintext creates no such path — the same reason its `reveal` conjunct is vacuous there. Machines never reauthenticate; the human performing the act does.

func (*Auth) ResetCredential

func (s *Auth) ResetCredential(ctx context.Context, actor Actor, targetPrincipal, delivery string) (ResetResult, error)

ResetCredential is the network tier: a credential-reset holder resets a target.

The org-bounded test is evaluated and acted on in ONE serializable transaction with the target's grant set (ADR - Recovery). The reset locks the target's `principals` row, which every grant mutation also locks (B14): a concurrent grant landing that would give the target instance authority or a second org conflicts with the in-flight reset, so the classification cannot go stale between the check and the mint.

func (*Auth) SAMLACS

func (s *Auth) SAMLACS(ctx context.Context, slug, encodedResponse, relayState, initiatorCookie string) (LoginResult, error)

SAMLACS validates one HTTP-POST response and completes the transaction's recorded purpose. Transaction consumption, replay insertion and the session or reauth write commit together; a concurrent replay can win only once.

func (*Auth) SAMLMetadata

func (s *Auth) SAMLMetadata(ctx context.Context, slug string) ([]byte, error)

SAMLMetadata publishes documentation-class SP material for one provider.

func (*Auth) SAMLStart

func (s *Auth) SAMLStart(ctx context.Context, slug, purpose, environmentID, presented, proof string) (SAMLStartResult, error)

SAMLStart creates the SP-initiated request and its durable purpose binding.

func (*Auth) SetPassword

func (s *Auth) SetPassword(ctx context.Context, presented, password, proof string) (LoginResult, error)

SetPassword sets the first password or replaces the existing one. Policy validation precedes credential work, and every session and window is retired atomically with the write. The acting session receives only the proof class.

func (*Auth) Signup

func (s *Auth) Signup(ctx context.Context, email string, org domain.OrgID) error

Signup commits intent before its single synchronous transport attempt. An admitted charge is never refunded.

func (*Auth) SlideIdleClock

func (s *Auth) SlideIdleClock(ctx context.Context, presented string, activity CallerActivity) error

SlideIdleClock advances a live session's idle expiry, at most once per SlideGranularity. The transport calls it after a successful response, so the write never sits between authorization and the answer.

The decision reuses the request's own authentication read, and a write is opened only when one is actually needed. That ordering matters more than it looks: a fabricated bearer has no resolved CallerActivity, so it cannot contend for sqlite's single write connection by supplying header noise.

It is a no-op — not an error — when the session has since died: the request it belonged to already succeeded, and failing here would report a problem that no longer has a subject.

func (*Auth) StartCLILogin

func (s *Auth) StartCLILogin(ctx context.Context, transport, state, challenge, redirect string) (CLILoginStart, error)

func (*Auth) StartCLIReauth

func (s *Auth) StartCLIReauth(ctx context.Context, presented string, intent ReauthIntent, pkceChallenge, redirectURI string) (CLIReauthStart, error)

func (*Auth) StepUpPasskeyFinish

func (s *Auth) StepUpPasskeyFinish(ctx context.Context, presented string, responseJSON []byte) (LoginResult, error)

StepUpPasskeyFinish validates the assertion, applies the sign-count rule, and appends webauthn to the acting session's factor set, rotating its token and preserving the original authenticated_at/ceremony (A21). Not an account-security mutation.

func (*Auth) StepUpPasskeyStart

func (s *Auth) StepUpPasskeyStart(ctx context.Context, presented string) ([]byte, error)

StepUpPasskeyStart opens a non-discoverable ceremony scoped to the acting account's credentials, to elevate the session in place.

func (*Auth) StepUpTOTP

func (s *Auth) StepUpTOTP(ctx context.Context, presented, code string) (LoginResult, error)

StepUpTOTP elevates the acting session in place: a valid code consumes its step (single-use CAS), then the session's factor set gains `totp` and its token rotates. It is NOT an account-security mutation — no generation advance, no session deletion — and it preserves the original authenticated_at/ceremony so repeated step-ups cannot reset absolute age (finding A21). Returns the rotated token.

func (*Auth) TOTPStatus

func (s *Auth) TOTPStatus(ctx context.Context, presented string) (TOTPStatusResult, error)

TOTPStatus reads the caller's OWN authenticator state. It is a pure read that mutates nothing and advances no generation. It reveals only what a caller could already learn by attempting an enrolment — a second start is refused by name — so the account surface can state the fact instead of disclaiming it.

func (*Auth) UnlinkIdentity

func (s *Auth) UnlinkIdentity(ctx context.Context, presented, identityID, proof string) (LoginResult, error)

UnlinkIdentity removes a linked identity as an account-security mutation. It refuses removing the last remaining credential (in the lockout-invariant shape), verifies the pre-existing password, and reissues the acting session.

func (*Auth) UpdateMyProfile

func (s *Auth) UpdateMyProfile(ctx context.Context, presented string, profile ProfileUpdate, proof string) (AccountProfile, error)

UpdateMyProfile requires fresh proof for username changes and preserves sessions: no credential, assurance, immutable principal, or grant changes. Provider subject keys and SCIM-owned names are never rewritten through this surface.

func (*Auth) VerifyBrowserCSRF

func (s *Auth) VerifyBrowserCSRF(ctx context.Context, presented, csrfToken string) error

VerifyBrowserCSRF checks a presented synchronizer token against the session row's verifier.

It is a transport duty, not an authorization one — #54 A10 fixes the CSRF REQUIREMENT in transport, and the check belongs with it — but the verifier lives on the session row, so the read happens here.

Two outcomes, and the difference is load-bearing:

  • domain.ErrUnauthenticated — the presented cookie resolves to no live session. There is nothing to protect: a dead artifact authorizes nothing, and refusing here would make a browser holding an expired cookie unable to log in again, since a login POST carries that cookie.
  • ErrCSRFMismatch — the session is live and the token is not its own. This is the refusal the gate exists for.

A CLI session reaching here is a mismatch, not a pass: it can only happen if a `cli` token was planted in the browser cookie, and a session with no CSRF verifier can satisfy no CSRF contract.

func (*Auth) VerifyReauthProof

func (s *Auth) VerifyReauthProof(ctx context.Context, presented, proof string) (ReauthEvidence, error)

VerifyReauthProof re-proves the acting human inside a request that performs a REAUTHENTICATION-GATED operation whose scope is not an environment.

The environment-keyed window machinery above is the disclosure gate: it keys on (session, environment) because that is what a reveal addresses. An org-scoped act like minting a provisioning credential has no environment, so it takes the shape the account-security mutations already use — a proof presented WITH the request and verified in it, `GenerateRecoveryCodes`'s pattern, extracted here so there is one implementation rather than two.

A caller with no session is LOCAL HOST AUTHORITY (the fixtures, and the below-the-network paths). It has nothing to reauthenticate and is exempt, the same exemption authorize() already makes for the MFA-mandatory rule.

The single proof field is read as whichever class the selection picks (the confirmed TOTP where one stands, else the password), so it is handed to the shared selector as both candidates.

func (*Auth) VerifySignup

func (s *Auth) VerifySignup(ctx context.Context, in SignupVerification) error

type AuthMethodProvider

type AuthMethodProvider struct {
	Profile     string
	Slug        string
	DisplayName string
	Kind        string
	// Brand names the provider whose published button rules the sign-in
	// surface follows (#587 d4): "google", "microsoft", or "" for generic.
	Brand string
}

AuthMethodProvider is one enabled provider for the public methods list.

type Backup

type Backup struct {
	DB      *store.DB
	Options backup.Options
	Now     func() time.Time
	// contains filtered or unexported fields
}

Backup is the export service. Options carries the recipient policy; a zero-recipient policy is refused by the container package rather than re-checked here, so there is exactly one place that decides it.

func (*Backup) Due

func (s *Backup) Due(ctx context.Context, interval time.Duration) (bool, error)

Due reports whether the scheduled export should run now: the scheduler ticks hourly and the interval is at least an hour, so the job gates itself on the persisted last success rather than on the tick. A never- exported instance is due immediately (startup catch-up).

func (*Backup) Export

func (s *Backup) Export(ctx context.Context, dir string) (ExportResult, error)

Export writes one age-encrypted archive into dir and returns where it landed. It does NOT write the audit event: an export can run against a datastore whose schema is about to change, and the record of it belongs after the migration that follows. RecordExport is the other half.

func (*Backup) ExportUpgrade

func (s *Backup) ExportUpgrade(ctx context.Context, dir string, plan upgradecompat.Plan, proposal *backupreceipt.LegacyProposal) (ExportResult, error)

ExportUpgrade publishes exact ciphertext first and its public receipt last. It accepts only public X25519 recipients and never loads private custody.

func (*Backup) LastExportSuccess

func (s *Backup) LastExportSuccess(ctx context.Context) (time.Time, bool, error)

LastExportSuccess is the scheduler's health probe shape.

func (*Backup) LastPruneSuccess

func (s *Backup) LastPruneSuccess(ctx context.Context) (time.Time, bool, error)

LastPruneSuccess is the scheduler's health probe shape for the pruner.

func (*Backup) ProveValuesReadable

func (s *Backup) ProveValuesReadable(ctx context.Context, kr *crypto.Keyring) (bool, error)

ProveValuesReadable is the drill's decrypt proof (#145). It reads ONE stored secret cell from the restored scratch instance under scheduler authority and opens it through the project sealer built on the SEPARATELY supplied root key, proving the custody pair (backup identity already used to decrypt the container, root key now) reconstitutes plaintext. It never returns, prints or logs the plaintext: the boolean is the whole answer.

func (*Backup) Prune

func (s *Backup) Prune(ctx context.Context, dir string, policy PrunePolicy) (PruneResult, error)

Prune records a durable attempt before touching files. Publication recording and pruning share cross-process datastore serialization: a success record cannot advance to a file between planning and unlink. Export itself needs no root key and never waits on this lock while taking a datastore snapshot.

func (*Backup) RecordDrill

func (s *Backup) RecordDrill(ctx context.Context, rep DrillReport) error

RecordDrill writes the drill's verdict to the LIVE instance: one audit event on the instance trail and the health row doctor reads. The drill itself ran against a scratch target; this is the only thing it leaves on the instance it was rehearsing for.

func (*Backup) RecordExport

func (s *Backup) RecordExport(ctx context.Context, trigger ExportTrigger, r ExportResult) error

RecordExport writes the export's audit event. It is separate from Export because the pre-migration export runs against the OLD schema and its record belongs in the new one.

func (*Backup) RecordFailure

func (s *Backup) RecordFailure(ctx context.Context, trigger ExportTrigger, runErr error) error

RecordFailure is the loud half of a scheduled export that did not happen: a configured policy was not honoured. It lands on the instance trail with a bounded error class (never the error text, which can quote a path) and updates the health row so doctor, the API and the metric all say so until the next success. Durable on purpose: an export failure that only reached a log line would convert the RPO to infinity silently.

func (*Backup) RecordSkip

func (s *Backup) RecordSkip(ctx context.Context, trigger ExportTrigger, reason string) error

RecordSkip is the LOUD half of "automatic pre-migration export when public recipients are configured, loud skip otherwise". The skip is non-fatal by the ops spec's own wording — a migration must not be blocked by an unconfigured backup — so the loudness has to come from somewhere that survives the morning after, which is the durable trail, not a log line nobody scrolls back to.

func (*Backup) State

func (s *Backup) State(ctx context.Context) (store.BackupState, error)

State reads the DR health row under scheduler authority. It is the scheduler's per-job success probe and the drill's before/after read.

type BackupHealth

type BackupHealth struct {
	Scheduled     bool
	LastSuccessAt time.Time
	ArtifactAge   time.Duration
	RPO           time.Duration
	// RPOExceeded is true when exports are scheduled and the newest
	// successful artifact is older than the RPO, or there has never been one.
	RPOExceeded             bool
	LastFailureAt           time.Time
	LastFailureReason       string
	LastPruneAt             time.Time
	LastPruneAttemptAt      time.Time
	RetainedExpiredArchives int64
	RetentionBreach         bool
	RetentionReason         string
	LastDrillAt             time.Time
	LastDrillOK             bool
	// DrillStale is true when no successful drill is younger than
	// DrillStaleAfter, whether or not exports are scheduled: a restore test
	// is owed regardless of how the archives are produced.
	DrillStale bool
}

BackupHealth is the DR half of the operator health read. Zero times mean "never"; the two verdict booleans are computed here, once, so doctor, the API and the metrics never disagree about what "exceeded" means.

type BackupPolicy

type BackupPolicy struct {
	Scheduled   bool
	Interval    time.Duration
	RPO         time.Duration
	RetainCount int
	RetainDays  int
	RTOTarget   time.Duration
}

BackupPolicy is the resolved DR schedule the health surface reasons against. Scheduled false means no export policy is configured: nothing runs, and health reports that rather than an RPO breach.

type BindingRequest

type BindingRequest struct {
	// Issuer is the byte-exact `iss` of a configured issuer.
	Issuer string
	// Subject is the byte-exact `sub`. No wildcards, no patterns, no prefixes.
	Subject string
	// Audience is mandatory and may not be the issuer's default.
	Audience string
	// RequiredClaims must be non-empty, and must pin `event_name` for a CI
	// issuer.
	RequiredClaims []ClaimPin
	// Indefinite and Lifetime are the same typed lifetime a bearer credential
	// carries, governed by the same instance ceiling and the same default-off
	// opt-in. Renewal is a mint.
	Indefinite bool
	Lifetime   time.Duration
	// Replaces names the binding this one supersedes. Because a binding is
	// immutable, every change is a replacement: the predecessor is revoked and
	// the successor inserted in ONE transaction, which is also what lets the
	// live-row unique index hold across the swap.
	Replaces string
}

BindingRequest is one binding mint.

type BindingView

type BindingView struct {
	CredentialID   string
	IssuerID       string
	Issuer         string
	IssuerType     domain.IssuerType
	Subject        string
	Audience       string
	RequiredClaims []ClaimPin
	Lifetime       domain.CredentialLifetime
	ExpiresAt      time.Time
	CreatedAt      time.Time
	CreatedBy      domain.PrincipalID
	RevokedAt      time.Time
	ReactivatedAt  time.Time
	ExpiringSoon   bool
	// Clamped reports that the instance ceiling shortened the requested
	// lifetime.
	Clamped bool
	// ReplacedID is the predecessor this mint revoked, empty when none.
	ReplacedID string
}

BindingView is a binding's metadata. There is no secret to omit — a binding holds nothing at rest — so unlike a bearer credential this view is complete.

type BootstrapDeployment

type BootstrapDeployment interface {
	Identity() DeploymentIdentity
	SeedSources(context.Context) (config.ManagedBootstrapSources, error)
	PrepareCommand(context.Context, configrollout.Intent, *runtimeconfig.Bundle, uint64) (configrollout.SignedCommand, error)
	// RootPreparation returns detached encrypted material only. The final exact-
	// MFA transaction must separately authorize and persist the root wrapper.
	RootPreparation(context.Context, configrollout.SignedCommand) (*crypto.WrappedKey, error)
	DecisionCommand(context.Context, configrollout.SignedCommand, configrollout.Action, uint64, string, *configrollout.ApplicationAcknowledgement) (configrollout.SignedCommand, error)
	// RenewCommand changes transport sequence/timestamps only. Its input must
	// come from a committed rollout row; preparation authority cannot be renewed.
	RenewCommand(context.Context, configrollout.SignedCommand, uint64) (configrollout.SignedCommand, error)
	Send(context.Context, configrollout.SignedCommand) error
	Response(context.Context, configrollout.SignedCommand) (configrollout.Response, error)
	VerifyInstalled(context.Context, *runtimeconfig.Bundle) error
}

BootstrapDeployment owns installed source proof and signed command transport. Service owns all durable jobs, sequence allocation, authorization and target changes. None of these methods writes Hikyo service/store state. In particular, DecisionCommand reproves/signs into private memory outside the final write transaction, avoiding another source-pool acquisition while it holds the only connection. The service then rechecks the bound decision, consumes exact MFA and atomically commits target plus signed command. It neither sends nor exposes the signature before commit; a worker sends only committed bytes.

type BootstrapResult

type BootstrapResult struct {
	Authority   string
	AuthorityID string
	AccountID   string
	PrincipalID domain.PrincipalID
	Username    string
	ExpiresAt   time.Time
}

BootstrapResult carries the one-time authority out to the caller, which is responsible for delivering it through the print triad. The value is in memory only, is returned exactly once, and is never re-displayed: if it lapses, a new one is minted from the CLI on the host.

type Budget

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

Budget is the ops-spec § 179 expensive-path availability layer plus the § 151 (§ 8) schema-revision rate limit: a per-scope windowed rate counter and a per-scope concurrency semaphore, applied to the named expensive categories. Every refusal wraps admission.ErrOverloaded, so the server renders the uniform 429 + Retry-After the spec requires for all overflow, exactly as the pre-auth admission budget does.

Deliberately in memory, single node, like admission.Limiter and the reveal gateLimiter: v1's locked deployment envelope is a single node with no HA (system-architecture ADR), so process-local state IS the whole instance's state. A durable rate/concurrency table would add a write per expensive request — amplifying exactly the load it bounds — to buy nothing this deployment shape can use. A multi-node build must replace this with shared state, which is why the constraint is written down here rather than discovered later.

A nil *Budget is a working no-op, so a build that wires no budget (the isolation harness, focused unit tests) enforces no expensive-path bounds — the same nil-is-disabled discipline Advisory uses. The production wiring in internal/app always constructs one.

func NewBudget

func NewBudget() *Budget

NewBudget constructs an enabled budget on the real clock.

func NewBudgetWithClock

func NewBudgetWithClock(now func() time.Time) *Budget

NewBudgetWithClock constructs an enabled budget with an owner-supplied clock, so integration tests can prove rate boundaries without elapsed-time refill. The clock must be non-nil and safe for concurrent budget requests.

func (*Budget) AdmitAuthenticatedAPI

func (b *Budget) AdmitAuthenticatedAPI(sessionID string) error

AdmitAuthenticatedAPI is called only with a live transaction-authenticated session, once per network request. It is independent of expensive-path budgets and includes reads and valid-but-forbidden operations.

func (*Budget) Enabled

func (b *Budget) Enabled() bool

Enabled reports the current enforcement policy. A nil budget is disabled.

func (*Budget) SetDevelopmentDisabled

func (b *Budget) SetDevelopmentDisabled(disabled bool)

SetDevelopmentDisabled changes enforcement without resetting rate history or outstanding slots. The application owner must validate the immutable development context; callers cannot obtain this object through an API.

type CLIDeviceAttempt

type CLIDeviceAttempt struct {
	Login    LoginResult
	Status   string
	Interval int
}

type CLILoginStart

type CLILoginStart struct {
	State, DeviceCode, UserCode, VerificationURI string
	ExpiresAt                                    time.Time
	Interval                                     int
}

type CLILoginTransaction

type CLILoginTransaction struct {
	Reference, Transport, RedirectURI, Instance string
	ExpiresAt                                   time.Time
}

type CLIReauthApproval

type CLIReauthApproval struct {
	Code, State, RedirectURI string
}

type CLIReauthEnvironmentPolicy

type CLIReauthEnvironmentPolicy struct {
	EnvironmentID          string
	EffectiveWindowSeconds int
	RequiresWebAuthn       bool
}

type CLIReauthRedeemed

type CLIReauthRedeemed struct {
	SessionToken string
	SessionID    string
	Windows      []ReauthResult
}

type CLIReauthStart

type CLIReauthStart struct {
	State     string
	ExpiresAt time.Time
}

type CLIReauthTransaction

type CLIReauthTransaction struct {
	DeveloperCredential                    *DeveloperCredentialReauthTarget
	State, Purpose, Operation, RedirectURI string
	Environments                           []CLIReauthEnvironmentPolicy
	// KeyIDs is the enumerated unit of a disclosure purpose (reveal, copy):
	// exactly the keys the one browser decision will cover. Empty for adapter.
	SelfConfig *SelfConfigReauthTarget
	KeyIDs     []string
	ExpiresAt  time.Time
}

type CallerActivity

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

CallerActivity is an opaque post-response slide hint. Its authz payload is deliberately hidden from transport: server code may pass it back to Auth, but cannot turn it into a principal or an authorization decision.

func ResolvedCallerActivity

func ResolvedCallerActivity(ctx context.Context) (CallerActivity, bool)

ResolvedCallerActivity returns the request's authentication result as an opaque slide hint. Fabricated bearers and public handlers return no value.

type CapacityUpdate

type CapacityUpdate struct {
	KeyLimitOverride        *int
	ExpectedRevision        int64
	ExpectedInstanceDefault int
	ExpectedInstanceMaximum int
}

CapacityUpdate binds a settings write to both the project revision and the operator policy displayed in the editor. Nil resets the project to inherit.

type CellSignal

type CellSignal struct {
	EnvironmentID  string
	KeyID          string
	Name           string
	Classification string
	// PendingVersionID is the caller's OWN live draft for this cell, "" when
	// they have none. It is the id a selective publish names.
	PendingVersionID string
	PendingOperation string
	// PendingByOthers reports that at least one other principal holds a draft
	// here -- the quieter collision marker, visible before publish time.
	PendingByOthers bool
	// ChangedInRevision is the environment's latest revision when this cell
	// moved in it, 0 otherwise. The "recently changed" signal.
	ChangedInRevision int64
}

CellSignal is one `(key, environment)` cell's matrix signals.

Both signals are computed on the RESOLVED value, which in a flat model is trivially the cell itself, and both degrade to write-presence for `secret` keys: the signal reports that someone WROTE here, never that the plaintext differs from the published one. A comparison status is itself an oracle -- a principal who can edit but not reveal could stage a guessed value and read "unchanged" to confirm it -- so no method here ever compares plaintexts.

type CertificateIssueRequest

type CertificateIssueRequest struct {
	Profile      string
	Issuer       string
	CSRPEM       string
	GenerateKey  bool
	KeyAlgorithm string
	CommonName   string
	DNSNames     []string
	IPAddresses  []string
	URIs         []string
	TTL          time.Duration
}

CertificateIssueRequest is one leaf request against a bound profile. Exactly one of CSRPEM or GenerateKey is set.

type CertificateIssueResult

type CertificateIssueResult struct {
	Certificate   CertificateView
	PrivateKeyPEM []byte
}

CertificateIssueResult carries the issued certificate and, for a server-generated key only, the private key: display-once, never stored, and the caller's to zero after writing it out.

type CertificateView

type CertificateView struct {
	ID               string
	EnvironmentID    string
	ProfileName      string
	IssuerID         string
	IssuerName       string
	IssuerVersion    int64
	Serial           string
	State            string
	KeySource        string
	KeyAlgorithm     string
	KeyFingerprint   string
	CommonName       string
	DNSNames         []string
	IPAddresses      []string
	URIs             []string
	NotBefore        time.Time
	NotAfter         time.Time
	CertificatePEM   string
	ChainPEM         string
	PrincipalID      string
	PrincipalClass   string
	RenewedFrom      string
	RenewedBy        string
	RevokedAt        *time.Time
	RevocationReason string
	CreatedAt        time.Time
	UpdatedAt        time.Time
}

CertificateView is an issuance record's public surface: metadata and the public certificate. There is no private-key field.

type ChangedKey

type ChangedKey struct {
	KeyID  string
	Name   string
	Change string
}

ChangedKey is one lineage row as reported. It carries no value in any form -- not the plaintext, not a length, not a digest, not a changed-from marker.

type CheckResult

type CheckResult struct {
	State           string
	BaseRevision    *int64
	CurrentRevision int64
	Differences     definitions.Diff
	Findings        []Finding
}

CheckResult is the drift diagnostic (#70 § Drift). Findings carries the non-blocking secret-scanning results of the submitted bundle (#74 SS3): a read-only dry-run that surfaces credential-shaped leaves without persisting or minting a token, so an operator sees a plan would be refused before running it.

type ClaimPin

type ClaimPin struct {
	Claim   string
	String  *string
	Number  *int64
	Boolean *bool
}

ClaimPin is one pinned claim, as a DISCRIMINATED scalar rather than a free-form JSON value.

Exactly one of the three value members is set, and that is what makes "a string is never folded to a number" true at the API boundary rather than only inside the validator: `repository_id: 123` and `repository_id: "123"` are two different requests that cannot be confused for one another, and an int64 survives the wire without passing through a float.

func DecodeClaimPins

func DecodeClaimPins(raw string) ([]ClaimPin, error)

DecodeClaimPins renders a stored pinned-claim document back as discriminated pins, for the read surface. It is the inverse of encodeClaimPins and refuses anything the encoder could not have produced.

type CloneResult

type CloneResult struct {
	Copied          []string
	UncopiedSecrets []string
	// Findings are the Surface-1 warnings the cloned CONFIG values produced
	// (#74), warn-not-block. Secret material is never scanned.
	Findings []Finding
}

CloneResult is what a clone-at-creation produced. UncopiedSecrets names, BY NAME, every `secret` the source held that this actor's authority could not duplicate: the ADR requires them enumerated in the creation result rather than left for the operator to discover as an empty cell.

type ConfigureTransitKeyRequest

type ConfigureTransitKeyRequest struct {
	MinEncryptVersion     *uint32
	MinDecryptVersion     *uint32
	RotationPeriodSeconds *int64
	Callers               *[]TransitCallerEntry
}

ConfigureTransitKeyRequest changes mutable policy; nil fields are unchanged.

type ConnectionView

type ConnectionView struct {
	ID         string
	Principal  domain.PrincipalID
	Label      string
	Kind       domain.CredentialKind
	PrefixHint string
	Lifetime   domain.CredentialLifetime
	ExpiresAt  time.Time
	CreatedAt  time.Time
	CreatedBy  domain.PrincipalID
	RevokedAt  time.Time
	LastUsedAt time.Time
	Live       bool
}

ConnectionView is one connection's metadata. There is no value field and no query that selects one: a credential is display-once at mint and write-only after.

type CopiedValue

type CopiedValue struct {
	KeyName                string
	DestinationEnvironment string
}

CopiedValue is one cell that landed.

type CopyRequest

type CopyRequest struct {
	SourceEnvironmentID       string
	KeyNames                  []string
	DestinationEnvironmentIDs []string
	// ConfirmProtected is the protected-environment confirmation. A protected
	// destination refuses the copy without it, by name.
	ConfirmProtected bool
}

CopyRequest is one copy-to / bulk-apply. Keys and destinations are both explicit: "copy everything" is what clone-at-creation is for, and an empty list quietly meaning "all" is how a mistyped bulk apply becomes an incident.

type CopyResult

type CopyResult struct {
	Copied []CopiedValue
	// Findings are the Surface-1 warnings the copied CONFIG values produced
	// (#74), warn-not-block: the copy succeeds and each finding names its rule
	// and key locator. Secret material is never scanned. No dismissal token —
	// keep-as-config lives on the stage path.
	Findings []Finding
}

CopyResult enumerates what moved, one entry per (key, destination).

type CreateAdapterRequest

type CreateAdapterRequest struct {
	Provider   string
	Origin     string
	Credential []byte
	Target     AdapterTargetInput
	// GitLab-only transport policy (#159). The pin and bundle are public
	// material; AllowPersonalToken is the documented protected opt-in for a
	// broader personal access token and is recorded in the audit payload.
	SPKIPin            string
	CABundlePEM        string
	AllowPersonalToken bool
}

type CreateDynamicProviderRequest

type CreateDynamicProviderRequest struct {
	Kind       string
	Origin     string
	TLSMode    string
	GrantRole  string
	Credential []byte
}

type CreatePairingInvite

type CreatePairingInvite struct {
	Phrase, Label                      string
	InviteLifetime, CredentialLifetime time.Duration
}

type CreateSSHCARequest

type CreateSSHCARequest struct {
	Name       string
	Algorithm  string
	PrivateKey []byte
}

CreateSSHCARequest creates a CA with a generated key, or imports one. PrivateKey is write-only protected input; the caller zeroes it.

type CreateSession

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

CreateSession describes a newly authenticated session. Factor verification, audit events and any provider-specific binding stay with the caller.

type CreateTransitKeyRequest

type CreateTransitKeyRequest struct {
	Name                  string
	Algorithm             string
	Custody               string
	AllowedOperations     []string
	RotationPeriodSeconds int64
	Exportable            bool
	Callers               []TransitCallerEntry
}

CreateTransitKeyRequest creates a named key (ADR D1-D3, D7).

type CredentialEstablishStatus

type CredentialEstablishStatus struct {
	Kind, Slug, DisplayName string
	ExpiresAt               time.Time
}

CredentialEstablishStatus describes the acting session's unused creation window. It is private account inventory, never public provider discovery.

type CredentialView

type CredentialView struct {
	ID         string
	Kind       domain.CredentialKind
	PrefixHint string
	Lifetime   domain.CredentialLifetime
	// ExpiresAt is the zero time for an indefinite credential.
	ExpiresAt  time.Time
	CreatedAt  time.Time
	CreatedBy  domain.PrincipalID
	RevokedAt  time.Time
	LastUsedAt time.Time
	// ExpiringSoon is the in-product expiry warning the ADR asks for first,
	// before any transport. It is computed, never stored: a stored flag would
	// be stale the moment the clock moved past it.
	ExpiringSoon bool
	// The binding half, populated only for an `oidc-federation` row and the
	// zero value for a bearer credential — the kind discriminates, so there is
	// no second boolean saying which half of the view is meaningful.
	//
	// A binding IS a credential row (#62), listed and revoked through these
	// routes, so its identity has to travel on the listing: an operator cannot
	// audit a byte-exact `(issuer, subject)` pair they cannot see, and the
	// contract has always said this row "carries the binding members instead"
	// of a prefix hint. `Issuer` is the byte-exact string rather than the
	// configuration's id, because the id is not what the external authority
	// presents and not what an operator compares against a cluster.
	Issuer         string
	Subject        string
	Audience       string
	RequiredClaims []ClaimPin
	// ReactivatedAt is the restore predicate's instant, zero unless this
	// binding has been through a restore. It is a permanent refusal floor, not
	// a quarantine window, and the surface that hides it hides the reason a
	// workload stopped authenticating.
	ReactivatedAt time.Time
}

CredentialView is a credential's metadata. There is no value field, and that absence is the display-once rule expressed in a type: nothing in the system returns a credential value after mint, so there is nowhere to read one from.

type CureResult

type CureResult struct {
	Binding string
	Org     domain.OrgID
	GrantID string
}

CureResult names one retention the cure released, so the caller can clear the binding's `lockout_retention` attention state through the AUDITED exit path rather than leaving it standing over a grant that is no longer retained.

type DEKRotation

type DEKRotation struct {
	Scope     string
	OrgID     string
	ProjectID string
	Version   uint32
}

DEKRotation is one `rotate-dek`: the scope rotated and the new active version.

type DEKScope

type DEKScope struct {
	Instance         bool
	OrgID, ProjectID string
}

DEKScope selects what rotate-dek / reencrypt operate on: one project's DEK, or the instance DEK. The zero value (Instance false, empty ids) is invalid and refused, so a caller that forgets to name a scope gets a loud error rather than silently rotating the wrong key.

type Definitions

type Definitions struct {
	// Owner policy bounds project overrides; zero uses documented defaults.
	DefaultKeysPerProject int
	MaxKeysPerProject     int
	DB                    *store.DB
	Keyring               *crypto.Keyring
	Advisory              *Advisory
	// Budget applies the § 151 schema-revision rate limit (60/h per project) to
	// the definitions-apply path, via prepareSchemaPublish. Nil disables it.
	Budget *Budget
	// Scan is the secret-scanning Surface-2 seam (#74 SS3, ADR §7 (b)/(c)): the
	// plan/apply chokepoints scan every author-controlled bundle leaf before an
	// immutable plan persists (plan) and re-scan on ruleset-snapshot skew (apply),
	// and `check` surfaces findings non-persisting. A nil ruleset is scanning-off
	// (a pre-#74 test); a booted server always wires it.
	Scan *scanning.Ruleset
	Now  func() time.Time
}

Definitions is the definitions Git-flow service: export / check / plan / apply / settings (#70, source-of-truth ADR). It owns no policy of its own — the pure diff lives in internal/definitions, the publish pipeline in publish.go — and stitches them to the store under one authorized transaction each.

func (*Definitions) Apply

func (s *Definitions) Apply(ctx context.Context, actor Actor, scope domain.Scope, planID string, opts ApplyOptions) (ApplyResult, error)

Apply is the one write path a git-mode project allows. It re-checks every pin the plan recorded, then executes the whole final definition set through the store layer in ONE transaction — creates, deletes, name swaps, presence, groups — bumps the revision once, and fans schema publish out over every environment immediately before commit.

func (*Definitions) Check

func (s *Definitions) Check(ctx context.Context, actor Actor, scope domain.Scope, raw []byte) (CheckResult, error)

Check classifies drift between a submitted bundle and current state, with no persistence. It is the diagnostic; plan is the gate.

func (*Definitions) Export

func (s *Definitions) Export(ctx context.Context, actor Actor, scope domain.Scope, portable bool) ([]byte, error)

Export renders the project's canonical definitions bundle. --portable strips the server-owned ids and the base revision, producing a template that applies cleanly to a fresh instance.

func (*Definitions) GetPlan

func (s *Definitions) GetPlan(ctx context.Context, actor Actor, scope domain.Scope, planID string) (PlanView, error)

GetPlan returns a stored plan's view.

func (*Definitions) GetSettings

func (s *Definitions) GetSettings(ctx context.Context, actor Actor, scope domain.Scope) (DefinitionsSettings, error)

GetSettings reads the project's definitions source and last-apply provenance.

func (*Definitions) Plan

func (s *Definitions) Plan(ctx context.Context, actor Actor, scope domain.Scope, raw []byte, acks []string) (PlanView, error)

Plan diffs a bundle against current state, pins it, and persists an immutable plan. The plan IS the impact preview: it renders deletions concretely and names the entries whose apply will need reveal.

func (*Definitions) PruneExpiredPlans

func (s *Definitions) PruneExpiredPlans(ctx context.Context) (int64, error)

PruneExpiredPlans deletes expired, unapplied plans across the instance. The hourly retention GC calls it; it mints the same scheduler system authority the payload sweep uses.

func (*Definitions) SetSettings

func (s *Definitions) SetSettings(ctx context.Context, actor Actor, scope domain.Scope, source string) (DefinitionsSettings, error)

SetSettings writes the project's definitions source. It rides `project-settings`, off the definitions-edit path (permission ADR §84).

type DefinitionsSettings

type DefinitionsSettings struct {
	Source    string
	LastApply *LastApply
	// CanDeclareKeys is the caller's own existential empty-key creation
	// affordance. Writes still authorize the chosen folder and environment.
	CanDeclareKeys *bool
	// CanEditDefinitions offers metadata editing where the caller holds Define;
	// it does not confer authority on other keys or on bulk definitions.
	CanEditDefinitions *bool
}

DefinitionsSettings is the settings view.

type DeleteResult

type DeleteResult struct {
	ProviderID      string
	RevokedLeaseIDs []string
}

DeleteResult reports which leases a delete queued for revocation.

type DeliveredKey

type DeliveredKey struct {
	// KeyID is the immutable key id (entry.KeyID), delivered so a client can
	// bind per-key offline disclosure records to a stable identity.
	KeyID          string
	Name           string
	Classification string
	Presence       delivery.Presence
	// Value is the delivered plaintext, non-nil IFF it actually crossed to this
	// caller. A nil Value on a `set` key is presence-only: the snapshot delivers
	// the key, but this caller may not receive its plaintext. A pointer, not a
	// string, because the empty string is a legitimate delivered value and
	// "delivered empty" must be distinguishable from "not delivered".
	Value *string
	// SnapshotReceipt exists only when this fetch actually delivered plaintext.
	SnapshotReceipt *string
}

DeliveredKey is one key as the machine surface delivers it: its name, its classification, its presence, and — iff the caller was authorized to receive it — its plaintext Value.

type Delivery

type Delivery struct {
	DB *store.DB
	// Keyring derives the scoped change-token and cursor keys. Nil refuses
	// every fetch.
	Keyring *crypto.Keyring
	// Federation validates a presented OIDC ID token BEFORE the transaction
	// opens. Nil means only bearer credentials may fetch, which is what a build
	// that did not wire federation should do.
	Federation *Federation
	// Budget applies the § 179 machine-fetch aggregate rate: 300/min per org,
	// 1000/min per instance, on top of § 5's per-principal fetch rate. Nil
	// disables it.
	Budget *Budget
	Now    func() time.Time
	// FetchProbe is a conformance-only retry seam. Production leaves it nil;
	// it is invoked immediately after attempt-local response state is reset.
	FetchProbe DeliveryConformanceProbe
}

Delivery owns the machine fetch surface.

func (*Delivery) Fetch

func (s *Delivery) Fetch(ctx context.Context, presented string, scope domain.Scope, cursor string, opts FetchOptions) (FetchResult, error)

Fetch delivers the authorized projection of the addressed environment, or reports that the caller's cursor is current.

`presented` is the raw artifact, because this is the one surface where the ARTIFACT CLASS decides how the caller is resolved: a `hik_` bearer credential resolves at the chokepoint from its verifier, while an OIDC ID token needs its signature checked against a cached JWKS first, outside any transaction. The branch is on the shape the caller sent, never on anything the server has yet decided to trust.

HTTP admission makes this surface machine-only from #113 onward. FetchAs remains available to below-the-network local authority so operators and conformance fixtures can exercise the delivery mechanism without forging a machine artifact.

func (*Delivery) FetchAs

func (s *Delivery) FetchAs(ctx context.Context, actor Actor, scope domain.Scope, cursor string, opts FetchOptions) (FetchResult, error)

FetchAs is Fetch with the caller already decided.

The split is where the artifact-class branch ends: everything past it is identical for a bearer credential, a federated binding and a human session, which is the ADR's "identical authority" made structural rather than asserted. It is exported because the below-the-network callers — the isolation harness and, later, any local-authority verb — resolve their principal by other means and must not have to forge an artifact to reach the same code.

func (*Delivery) ListTargets

func (s *Delivery) ListTargets(ctx context.Context, actor Actor, scope domain.Scope) (DeliveryTargetList, error)

ListTargets is the human view of one environment (ADR D7: `read` on it). Rows of an environment the caller cannot read are absent: the whole list is the uniform nonexistent answer.

func (*Delivery) PurgeExpiredTargets

func (s *Delivery) PurgeExpiredTargets(ctx context.Context) error

PurgeExpiredTargets is the hourly 30-day purge (ADR D6), across every tenant: rows with no accepted report for 30 days, one committed batch at a time until the backlog is drained. Each purge emits its tenant-trail event under scoped scheduler authority, in the transaction that deletes the row.

func (*Delivery) ReconcileOfflineRecords

func (s *Delivery) ReconcileOfflineRecords(ctx context.Context, presented string, scope domain.Scope, records []OfflineRecord) (ReconcileResult, error)

ReconcileOfflineRecords authenticates a live presenter and persists the client-side disclosure facts that were fsynced before offline plaintext was released. Dedupe is scoped to the presenting principal, so retries are safe.

The per-key event stays audit.EventValueRevealed (disclosure.value_revealed, surface: offline-serve) rather than #64's audit.EventDisclosure: that event requires a snapshot `revision` an offline record does not carry, references a fetch envelope this path has no equivalent for, and lacks the served_credential _id/generation/served_from fields the offline disclosure records. Extending EventValueRevealed's schema with those (optional) fields is the clean home.

func (*Delivery) ReconcileOfflineRecordsAs

func (s *Delivery) ReconcileOfflineRecordsAs(ctx context.Context, actor Actor, scope domain.Scope, records []OfflineRecord) (ReconcileResult, error)

ReconcileOfflineRecordsAs is ReconcileOfflineRecords with the caller decided.

func (*Delivery) RefuseOversizeReport

func (s *Delivery) RefuseOversizeReport(ctx context.Context, presented string, scope domain.Scope) error

RefuseOversizeReport is the size refusal (413). The transport calls it INSTEAD of parsing a body over deliverytarget.MaxReportBytes: the caller is authenticated and authorized like any report, so an unauthorized caller still gets the uniform nonexistent answer, and the refusal is audited under no row, because the server never reads a key out of an over-size body.

func (*Delivery) ReportFileTarget

func (s *Delivery) ReportFileTarget(ctx context.Context, presented string, scope domain.Scope, targetID string, report FileTargetReport) error

ReportFileTarget authenticates the presented artifact and records one file-target report.

func (*Delivery) ReportFileTargetAs

func (s *Delivery) ReportFileTargetAs(ctx context.Context, actor Actor, scope domain.Scope, targetID string, report FileTargetReport) error

ReportFileTargetAs records the bound client's value-free report: the state it reached, the revision and target generation it rendered, and its keyed generation stamp. Only the bound principal may report, and only in the target's environment; anything else is the uniform nonexistent answer.

func (*Delivery) ReportTarget

func (s *Delivery) ReportTarget(ctx context.Context, presented string, scope domain.Scope, report deliverytarget.Report) error

ReportTarget authenticates the presented artifact and applies one report.

func (*Delivery) ReportTargetAs

func (s *Delivery) ReportTargetAs(ctx context.Context, actor Actor, scope domain.Scope, report deliverytarget.Report) error

ReportTargetAs upserts the caller's row for one target, or refuses.

func (*Delivery) TombstoneTarget

func (s *Delivery) TombstoneTarget(ctx context.Context, presented string, scope domain.Scope, key DeliveryTargetKey) error

TombstoneTarget authenticates the presented artifact and deletes one row.

func (*Delivery) TombstoneTargetAs

func (s *Delivery) TombstoneTargetAs(ctx context.Context, actor Actor, scope domain.Scope, key DeliveryTargetKey) error

TombstoneTargetAs deletes the caller's row for one target after its tombstone event (ADR D6). A tombstone naming no row of the caller's is the uniform nonexistent answer.

type DeliveryConformanceProbe

type DeliveryConformanceProbe interface {
	AfterAttemptReset(out *FetchResult) error
}

type DeliveryTarget

type DeliveryTarget struct {
	ID          string
	PrincipalID string
	Report      deliverytarget.Report
	ReceivedAt  time.Time
	State       string
	// RefusalCause and RefusedAt are set only while State is `refused`.
	RefusalCause string
	RefusedAt    time.Time
}

DeliveryTarget is one row with its read-time derived state.

type DeliveryTargetKey

type DeliveryTargetKey struct {
	ClusterID   string
	InstanceUID string
	UID         string
}

DeliveryTargetKey names one target of the caller's own: the principal is always the caller, never the body.

type DeliveryTargetList

type DeliveryTargetList struct {
	Reporters []DeliveryTargetReporter
	Targets   []DeliveryTarget
}

DeliveryTargetList is one environment's delivery-target view (ADR D2, D5): the server-observed layer per reporting principal and the controller- reported rows, never merged into one health bit.

type DeliveryTargetReporter

type DeliveryTargetReporter struct {
	PrincipalID string
	// LastContactAt is the last identity.delivery_fetched in this environment.
	LastContactAt time.Time
	// QuotaRefusedAt is the closed quota-refused notice.
	QuotaRefusedAt time.Time
}

DeliveryTargetReporter is the server-observed layer for one principal that owns rows here. A zero time is "never".

type DeploymentIdentity

type DeploymentIdentity struct {
	EnrollmentID    string
	OwnerInstanceID string
	Incarnation     string
	DeploymentUID   string
	TemplateStamp   string
}

DeploymentIdentity is metadata from operator-installed custody and the Pod's downward selection projection. TemplateStamp must match the durable prepared response before the coordinator acknowledges a deployed application generation.

type DesiredGroup

type DesiredGroup struct {
	DisplayName string
	ExternalID  string
	Members     []string
}

DesiredGroup is the complete group state accepted by create and PUT.

type DesiredUser

type DesiredUser struct {
	UserName   string
	ExternalID string
	// Active is already defaulted by the transport: omitted create/PUT input
	// arrives as true, while an explicit false remains false.
	Active bool
	// SubjectRaw is identity material for below-wire callers. Wire callers use
	// Attributes so the service can extract the binding's declared source.
	SubjectRaw string
	// Attributes is opaque display metadata after interpreted SCIM fields have
	// been removed.
	Attributes map[string]any
}

DesiredUser is the complete user state accepted by create and PUT. PATCH commands never inhabit this type: they are reduced into it before storage.

func ReduceUserPatch

func ReduceUserPatch(current DesiredUser, commands []UserPatchCommand) (DesiredUser, error)

ReduceUserPatch applies commands sequentially without mutating current.

type DeveloperCredential

type DeveloperCredential = authz.DeveloperCredential

type DeveloperCredentialReauthTarget

type DeveloperCredentialReauthTarget struct {
	Lifetime                time.Duration `json:"lifetime"`
	ConsentCurrentAndFuture bool          `json:"consent_current_and_future"`
}

type DeveloperCredentials

type DeveloperCredentials struct {
	DB   *store.DB
	Auth *Auth
	Now  func() time.Time
}

func (*DeveloperCredentials) List

func (*DeveloperCredentials) Mint

func (*DeveloperCredentials) Policy

func (s *DeveloperCredentials) Policy(ctx context.Context, actor Actor) (time.Duration, error)

func (*DeveloperCredentials) Revoke

func (s *DeveloperCredentials) Revoke(ctx context.Context, actor Actor, scope domain.Scope, id string, all bool) error

func (*DeveloperCredentials) SetPolicy

func (s *DeveloperCredentials) SetPolicy(ctx context.Context, actor Actor, ceiling time.Duration) (time.Duration, error)

type DiagnosticFinding

type DiagnosticFinding struct{ Code, Severity, Message string }

type DiagnosticHealth

type DiagnosticHealth struct {
	Findings      []DiagnosticFinding
	Volume        storagehealth.Health
	EscrowCurrent bool
	Metadata      store.OpsMetadata
}

type Diagnostics

type Diagnostics struct {
	Passwords *crypto.PasswordParams
	Volume    func() (storagehealth.Capacity, error)
}

Diagnostics contains only boot-validated policy and an authoritative datastore filesystem reader. A nil reader or policy reports unknown, never defaults.

type DiffRow

type DiffRow struct {
	KeyID          string
	Name           string
	Classification string
	Left           ValueCell
	Right          ValueCell
	// Equal is nil where the comparison could not be made without disclosing
	// something the caller may not see.
	Equal *bool
}

DiffRow is one key's two-sided comparison. Same disclosure rules as ValueCell, applied per side: without the reveal gate a `secret` row reports write-presence only, and Equal is left unanswered — whether two secrets match is itself material a non-revealer may not have.

type Discovery

type Discovery struct{ DB *store.DB }

Discovery exposes the stable instance identity without tenant metadata. It is the same persisted identity used by the pinned remote-add check.

func (*Discovery) InstanceIdentity

func (s *Discovery) InstanceIdentity(ctx context.Context) (string, error)

type DrillReport

type DrillReport struct {
	Archive        string
	ArchiveDigest  string
	Engine         store.Engine
	SchemaVersion  int64
	BinaryVersion  string
	Elapsed        time.Duration
	RTOTarget      time.Duration
	ValuesReadable bool
	Principal      string
	Minted         bool
	// FailedStep names the first step that did not complete; empty when
	// every step passed. A recorded failure is still a completed drill: the
	// operator learns the recovery path is broken while it is still a drill.
	FailedStep string
}

DrillReport is what a restore drill hands back to be recorded: identity of the archive, the versions involved, the clock, and the step verdicts. It carries no secret material by construction: there is no field for one.

func (DrillReport) OK

func (d DrillReport) OK() bool

OK reports whether every step passed AND the clock met the RTO target.

type Dynamic

type Dynamic struct {
	DB              *store.DB
	Auth            *Auth
	Keyring         *crypto.Keyring
	Budget          *Budget
	Runtime         *store.DynamicRuntime
	ProviderFactory dynamic.Factory
	// LeaseDeadline bounds one worker term's provider work; it must be shorter
	// than the claim lease so a slow provider cannot outlive the crash fence.
	LeaseDeadline time.Duration
	Now           func() time.Time
}

Dynamic owns the dynamic-secret surface (#147): PostgreSQL providers (project-scoped standing authority) and leases (environment-scoped, short- lived credentials). Mint is synchronous because the credential is disclosed once and never stored; renew, revoke, expiry, and settle are worker-driven and durable across restart.

func (*Dynamic) Configure

func (*Dynamic) Delete

func (s *Dynamic) Delete(ctx context.Context, actor Actor, scope domain.Scope, providerID string, revokeAll bool) (DeleteResult, error)

func (*Dynamic) Get

func (s *Dynamic) Get(ctx context.Context, actor Actor, scope domain.Scope, providerID string) (DynamicProviderView, error)

insertInspected records the manage-identities-gated read of provider metadata, mirroring adapter.inspect. A privileged read audits; only a bare-read lease inspect is auditedNone.

func (*Dynamic) GetLease

func (s *Dynamic) GetLease(ctx context.Context, actor Actor, scope domain.Scope, leaseID string) (DynamicLeaseView, error)

func (*Dynamic) List

func (s *Dynamic) List(ctx context.Context, actor Actor, scope domain.Scope) ([]DynamicProviderView, error)

func (*Dynamic) ListLeases

func (s *Dynamic) ListLeases(ctx context.Context, actor Actor, scope domain.Scope) ([]DynamicLeaseView, error)

func (*Dynamic) MintLease

func (s *Dynamic) MintLease(ctx context.Context, actor Actor, scope domain.Scope, req MintLeaseRequest) (MintLeaseResult, error)

func (*Dynamic) RenewLease

func (s *Dynamic) RenewLease(ctx context.Context, actor Actor, scope domain.Scope, leaseID string, maxTTLSeconds int64) (DynamicLeaseView, error)

func (*Dynamic) ReplaceCredential

func (s *Dynamic) ReplaceCredential(ctx context.Context, actor Actor, scope domain.Scope, providerID string, credential []byte) error

func (*Dynamic) RevokeCredential

func (s *Dynamic) RevokeCredential(ctx context.Context, actor Actor, scope domain.Scope, providerID string) error

func (*Dynamic) RevokeLease

func (s *Dynamic) RevokeLease(ctx context.Context, actor Actor, scope domain.Scope, leaseID string) (DynamicLeaseView, error)

func (*Dynamic) RunLeaseSweep

func (s *Dynamic) RunLeaseSweep(ctx context.Context, workerID string) (bool, error)

RunLeaseSweep claims and settles one due lease transition. It returns true when it did work (so the scheduler job can loop until idle). It is the body the fenced dynamic-lease scheduler runs under #146's singleton lease, so at most one node ever executes a given lease's transition.

func (*Dynamic) SettleLease

func (s *Dynamic) SettleLease(ctx context.Context, actor Actor, scope domain.Scope, leaseID string) (DynamicLeaseView, error)

type DynamicLeaseView

type DynamicLeaseView struct {
	store.DynamicLease
}

type DynamicProviderView

type DynamicProviderView struct {
	store.DynamicProviderRecord
}

type EnvDeletion

type EnvDeletion struct {
	Name        string `json:"name"`
	Occurrences int64  `json:"occurrences"`
}

EnvDeletion is one deleted environment with its live-occurrence count.

type Environment

type Environment struct {
	ID           string
	OrgID        string
	ProjectID    string
	Name         string
	Note         string
	DisplayOrder int64
	CreatedAt    time.Time
}

Environment is the service layer's environment. DisplayOrder is its user-defined position within the project. There is no base pointer and no defaults layer to expose, because neither exists.

type EnvironmentSettings

type EnvironmentSettings struct {
	Protected         bool
	ExpectedProtected *bool
	// HasWindow false means the environment inherits the instance default.
	HasWindow bool
	Window    time.Duration
}

EnvironmentSettings is the caller-facing shape of the two knobs.

type EnvironmentSignals

type EnvironmentSignals struct {
	EnvironmentID string
	Revision      int64
	Cells         []CellSignal
}

EnvironmentSignals is one environment's advisory state: its current revision and its cells' signals. It is the SSE channel's documented polling fallback as well as the matrix's ordinary read.

type Environments

type Environments struct {
	DB      *store.DB
	Keyring *crypto.Keyring
	// Auth supplies the reveal guard for clone-at-creation (#58): a clone
	// duplicates stored `secret` material, which is a disclosure by proxy, so
	// its source side takes the same enumerated-key ceremony a cell reveal
	// does. Nil refuses a clone that would open secrets, loudly.
	Auth *Auth
	// Advisory announces topology changes and new revision 1, after commit.
	Advisory *Advisory
	// Budget applies the § 151 schema-revision rate limit (60/h per project):
	// creating, renaming or deleting an environment bumps the project's schema
	// revision, so it charges the same per-project budget key-catalogue edits do.
	// Nil disables it.
	Budget *Budget
	// Scan: secret-scanning Surface-2 seam (#74). Environment names and notes
	// are author-controlled declaration text.
	Scan *scanning.Ruleset
}

Environments owns the environment surface.

The Keyring is here only for clone-at-creation (#50): cloning re-seals every copied value under the destination row's own AAD, and that has to happen in the same transaction that creates the environment. A build without one can still create environments; it refuses to clone, loudly.

func (*Environments) Clone

func (s *Environments) Clone(ctx context.Context, actor Actor, scope domain.Scope, name, sourceEnvID string, acks []string) (Environment, CloneResult, error)

Clone is create-with-clone-at-creation (#50, flat-model ADR § Ergonomics): the new environment is born holding a copy of another environment's values.

It is ONE act. The environment row, every copied value and the audit records for both commit together or not at all — the atomicity rule admits no partially-valid creation, and a clone that aborted after creating the environment would leave exactly that.

The copy is preflighted, and the preflight can ABORT the creation: see cloneInto. What could not be copied comes back enumerated by name, never silently absent.

func (*Environments) Create

func (s *Environments) Create(ctx context.Context, actor Actor, scope domain.Scope, name string, acks []string) (Environment, error)

Create appends an environment at the end of the project's display order. The count that bounds it is read under the same proof in the same transaction as the insert, so the cap cannot be walked past by two concurrent creates.

func (*Environments) Delete

func (s *Environments) Delete(ctx context.Context, actor Actor, scope domain.Scope) error

Delete removes an environment. The remaining environments keep their positions: display order is a property of each row, not an invariant over the set, so a gap is not a defect and closing it would be an unrequested write to rows the operator did not name.

func (*Environments) Get

func (s *Environments) Get(ctx context.Context, actor Actor, scope domain.Scope) (Environment, error)

func (*Environments) List

func (s *Environments) List(ctx context.Context, actor Actor, scope domain.Scope) ([]Environment, error)

List returns the project's environments in display order.

func (*Environments) ListPage

func (s *Environments) ListPage(ctx context.Context, actor Actor, scope domain.Scope, afterDisplayOrder int64, afterName string, limit int) ([]Environment, error)

ListPage is the bounded keyset read behind hikyo_list_environments. The stable order matches List exactly: display order then UNIQUE environment name. afterDisplayOrder is -1 and afterName is "" for the first page.

func (*Environments) Parameters

func (s *Environments) Parameters(ctx context.Context, actor Actor, scope domain.Scope) (map[string]string, error)

func (*Environments) Rename

func (s *Environments) Rename(ctx context.Context, actor Actor, scope domain.Scope, name string, acks []string) (Environment, error)

func (*Environments) Reorder

func (s *Environments) Reorder(ctx context.Context, actor Actor, scope domain.Scope, ordered []string) ([]Environment, error)

Reorder rewrites the project's whole display order from an ordered id list.

It takes the WHOLE set rather than one position per call for two reasons: a single transaction cannot then leave two environments sharing a position or a gap in the sequence, and a concurrent reorder serializes behind it instead of interleaving with it. The list must name exactly the project's environments, once each; anything else is refused with one fixed message, which is also why a foreign id discloses nothing — the refusal is the same whether it exists or not.

func (*Environments) SetParameter

func (s *Environments) SetParameter(ctx context.Context, actor Actor, scope domain.Scope, name, pattern string, remove bool) error

SetParameter changes declarations for the next publication only. Existing delivery remains bound to the immutable contract captured by its snapshot.

func (*Environments) UpdateNote

func (s *Environments) UpdateNote(ctx context.Context, actor Actor, scope domain.Scope, note string, acks []string) error

UpdateNote mutates an environment's operator note. It is the edit-authority demonstration operation from #44 and has no HTTP route of its own; it stays because the isolation probes ride on it to prove that `edit(E)` and `definitions-edit(project)` are enforced as different authorities.

type Escrow

type Escrow struct {
	DB  *store.DB
	Now func() time.Time
}

Escrow is a CLI-only local custody operation. It does not authenticate a network caller and must never be wired to an HTTP handler.

func (*Escrow) Verify

func (s *Escrow) Verify(ctx context.Context, root []byte, separateCustodyAsserted bool) error

Verify consumes the supplied key. The caller checks distinct file custody; the assertion records the operator's claim, not physical offline proof.

type ExportMetadataWriter

type ExportMetadataWriter interface {
	BeginAuditExport(startedEventID string, snapshotTime time.Time)
}

ExportMetadataWriter optionally binds a streaming sink to its durable INTENT and effective inclusive recorded_at upper bound, before the first event byte. Calling this method does not authorize any further trail disclosure.

type ExportOutcome

type ExportOutcome string

ExportOutcome is how one export run ended. The first three are the outcome of its terminal export_completed event; ExportRevoked has no terminal event (see ErrExportUnpaired).

const (
	ExportSucceeded    ExportOutcome = "success"
	ExportFailed       ExportOutcome = "failure"
	ExportDisconnected ExportOutcome = "disconnected"
	ExportRevoked      ExportOutcome = "revoked"
)

type ExportReceipt

type ExportReceipt struct {
	StartedEventID  string
	SnapshotTime    time.Time
	RowsStreamed    int
	Outcome         ExportOutcome
	Cause           string
	OutcomeRecorded bool
}

ExportReceipt is the run's own account of an export whose INTENT is durable: the started event, the rows written to the sink, and how the run ended. OutcomeRecorded tells whether the paired export_completed event is durable. The receipt counts rows; it does not attest that the trail has no sequence gaps. A zero StartedEventID means the export stopped before its INTENT committed, so nothing was streamed.

type ExportResult

type ExportResult struct {
	ReceiptPath string
	Receipt     *backupreceipt.Receipt
	Path        string
	Bytes       int64
	Manifest    store.Manifest
	// contains filtered or unexported fields
}

ExportResult describes a durably published artifact.

func ExportPreparedUpgrade

func ExportPreparedUpgrade(ctx context.Context, db *store.PreparationDB, options backup.Options, dir string, plan upgradecompat.Plan, proposal *backupreceipt.LegacyProposal) (ExportResult, error)

ExportPreparedUpgrade accepts only the narrow, live-session preparation capability. It cannot construct a runtime DB or publish audit/domain writes.

type ExportTrigger

type ExportTrigger string

ExportTrigger says why an export ran, and rides the audit event: an operator asking for one and a migration taking one automatically are different facts about the same artifact.

const (
	// TriggerManual is `hikyo backup export`.
	TriggerManual ExportTrigger = "manual"
	// TriggerPreMigration is the automatic export the ops spec requires
	// immediately before a schema change.
	TriggerPreMigration ExportTrigger = "pre-migration"
)
const TriggerScheduled ExportTrigger = "scheduled"

TriggerScheduled is the in-process scheduler's export.

type ExportedValue

type ExportedValue struct {
	Name           string
	Classification string
	Value          string
	// Revealed says whether Value carries plaintext. A `config` value rides
	// `read`; a `secret` needs the reveal gate, and without it the row reports
	// write-presence with an empty value rather than being dropped -- a missing
	// row and an unreadable row are different facts.
	Revealed bool
}

ExportedValue is one key of an exported snapshot.

type ExternalIdentityView

type ExternalIdentityView struct {
	Slug        string
	DisplayName string
	Profile     string
	ID          string
	Kind        string
	Issuer      string
	Subject     string
	ProviderID  string
	CreatedAt   time.Time
}

ExternalIdentityView is the transport-facing shape of a linked identity, so internal/server needs no authz import.

type FederatedCaller

type FederatedCaller struct {
	IssuerID string
	Subject  string
	// Check is the binding half of validation, closed over the issuer
	// configuration and the token's claims. The chokepoint refuses a nil one.
	Check authz.BindingPredicate
	// contains filtered or unexported fields
}

FederatedCaller is a validated federated presentation: the issuer it names and the binding predicate its claims imply.

It exists because the two halves of federated authentication must happen on opposite sides of a transaction boundary. Validation needs the network (a JWKS refresh) and must therefore run BEFORE any transaction opens — on sqlite a hung issuer inside a write transaction would stall every writer in the instance. Binding resolution must happen INSIDE the authorizing transaction, uncached, because that is what makes revocation bite at the next fetch.

type Federation

type Federation struct {
	DB *store.DB
	// Auth supplies the reauthentication conjunct for a binding mint. Machines
	// never reauthenticate; the human creating the binding does.
	Auth *Auth
	// Cache is the JWKS cache. Nil means federated presentation is refused,
	// which is the correct posture for a build that did not wire it.
	Cache *oidcfed.Cache
	// Admission is the instance-wide pre-authentication budget. The ADR is
	// explicit that it covers federated validation, not only human paths:
	// "pre-authentication admission limits apply to credential presentation and
	// to federated validation, under the same instance-wide budget". Federated
	// validation is the more expensive of the two — an RSA verify per presented
	// token, and on a cache miss an outbound fetch — so it is the one that most
	// needs a slot. Nil means unlimited, which is only for tests.
	Admission *admission.Limiter
	Now       func() time.Time
	// OnValidated runs between the pre-transaction validation and the caller's
	// authorizing transaction. It exists for exactly one fixture: the window an
	// administrator's issuer update can land in is real but unobservable from
	// outside, and a test that raced it with goroutines would be flaky rather
	// than a proof. Nil in production, and nothing else may use it.
	OnValidated func()
}

Federation owns the federation surface. Like every service here it opens one transaction, authorizes inside it, and performs the whole mutation before it commits — with one deliberate exception, Authenticate, whose network half runs BEFORE any transaction opens.

func (*Federation) Authenticate

func (s *Federation) Authenticate(ctx context.Context, presented string) (FederatedCaller, error)

Authenticate is the PRE-TRANSACTION half of federated authentication: peek at the unverified issuer, resolve its configuration, refresh the JWKS cache if the age or an unknown `kid` calls for it, and validate the token completely.

Every failure answers the SAME error — domain.ErrUnauthenticated — whatever the cause. The cause reaches the audit trail and nothing else, which is the unauthorized-is-indistinguishable-from-nonexistent rule one layer earlier than the chokepoint.

func (*Federation) CreateBinding

func (s *Federation) CreateBinding(ctx context.Context, actor Actor, scope domain.Scope, saID string, req BindingRequest) (BindingView, error)

CreateBinding mints a federated binding.

The authorization formula is the ADR's SECOND minting row, and it ranges over the WHOLE post-state rather than over anything the mint adds — a binding adds no grants at all, so an "added environments" reading would require `reveal` on nothing and let a principal holding `manage-identities` and no `reveal` re-point a production binding at an identity they control.

func (*Federation) CreateIssuer

func (s *Federation) CreateIssuer(ctx context.Context, actor Actor, req IssuerRequest) (IssuerView, error)

CreateIssuer configures an issuer under `instance-config`.

func (*Federation) DeleteIssuer

func (s *Federation) DeleteIssuer(ctx context.Context, actor Actor, id string) error

DeleteIssuer removes a configuration, refusing while live bindings name it.

The refusal is not politeness. A cascade would revoke every binding underneath, which is a deprovisioning of N workloads performed by an operation whose name says "configuration"; and a delete that orphaned the rows would leave bindings whose issuer cannot be resolved, i.e. bindings that silently stop authenticating. The operator revokes the bindings first, which is the same act stated honestly.

func (*Federation) ListIssuers

func (s *Federation) ListIssuers(ctx context.Context, actor Actor) ([]IssuerView, error)

ListIssuers reads every configured issuer with its live-binding census.

Audited rather than `audited: none`: the audit model's default-deny permit rule admits only tenant-class bare-`read` operations, and reading which external authorities the instance trusts is neither.

func (*Federation) Reactivate

func (s *Federation) Reactivate(ctx context.Context, actor Actor, scope domain.Scope, saID, credentialID string) (time.Time, error)

Reactivate records a restore-time re-validation of one binding (§ Restore).

A binding may be re-activated where a bearer verifier may never be, and the asymmetry is not leniency: a binding holds no bearer value, so there is nothing an attacker can have captured and nothing to redistribute. What it still needs is the `iat` predicate, because a restore can resurrect a binding that was removed precisely BECAUSE that workload was compromised.

#76 owns the operator ceremony (recovery mode, per-principal, no bulk-accept). This is the write it will call, and it exists now because the refusal it arms — every later token must have been issued after re-activation, by a margin that swallows clock skew — is what this ticket had to prove.

func (*Federation) RecordBindingRefusal

func (s *Federation) RecordBindingRefusal(ctx context.Context, issuer, cause string) error

RecordBindingRefusal records a refusal the CHOKEPOINT produced — an unbound identity, a revoked binding, a failed binding predicate — which the pre-transaction half cannot see, because the row it turns on is read only inside the operation's transaction.

It must be called AFTER that transaction has ended, not inside it. Two reasons, both real: the operation's transaction rolled back, so an event staged inside it would be a durable record that is not durable; and on sqlite a nested write transaction deadlocks against the single writer until the retry deadline elapses.

It records ONE cause for all three outcomes, and the collapse is deliberate. The resolution surface hands the binding predicate a DECOY binding on a miss — which is what keeps an unbound identity from being the cheap case — so the predicate's verdict on a miss is the decoy's verdict, not any real binding's. Reporting it as a cause would therefore sometimes report the decoy. The PRE-transaction causes (unknown issuer, unavailable or stale keys, signature, token age, audience) are reported individually, because nothing decoy-shaped is involved in producing them.

func (*Federation) UpdateIssuer

func (s *Federation) UpdateIssuer(ctx context.Context, actor Actor, id string, source jwkssource.KeySource, refused []string, caBundle *string) (IssuerView, error)

UpdateIssuer moves the MUTABLE half — the JWKS source and the refused audiences. It cannot move the issuer string or the platform type: changing either would silently re-point every binding underneath at a different external authority, which is a replacement, not an edit.

type FetchOptions

type FetchOptions struct {
	Parameters map[string]string
	// Projection is the delivery projection. The empty value means `full`.
	Projection delivery.Mode
	// AcknowledgedKeys is the loader-control acknowledgement, recorded on the
	// fetch audit record AS PRESENTED and otherwise ignored — the server filters
	// nothing and refuses nothing on it (k8s ADR § Loader-control).
	AcknowledgedKeys []string
	// Target names the file target (#164) the caller is bound to. A workload
	// bound to a file target is delivered that target's key selection only and
	// must name it; any other caller naming a target gets the uniform
	// nonexistent answer.
	Target string
}

FetchOptions carries the per-request delivery controls that are not the cursor: the projection mode and the acknowledged loader-control keys. It is a struct rather than positional arguments so the two can grow without churning every caller again, and its zero value is the default fetch — `full` projection, no acknowledgement — which is what the below-the-network callers that do not care about either want.

type FetchResult

type FetchResult struct {
	// Current reports that the presented cursor named the state the server was
	// about to serve. NO CONTENT accompanies it — that is the whole point: only
	// a fetch that actually delivers is a disclosure.
	Current bool
	// Cursor is the opaque cursor for the state this answer describes. It is
	// returned on BOTH dispositions: a caller told "current" must be able to
	// keep polling without having to re-fetch to learn its own cursor.
	Cursor string
	// ChangeToken is the keyed delivery-manifest token, `v1:`-prefixed. It is
	// change-detection material ONLY — the conditional-fetch cursor's input —
	// and is never itself a workload-visible value (k8s ADR § Declared
	// amendment): what reaches a pod annotation is the consumer's client-side
	// per-target keyed stamp, not this token. It is non-secret metadata by
	// construction (keyed, not a digest of content), so it may flow into logs
	// and change-detection caches.
	ChangeToken string
	// CredentialExpiresAt is the presenting credential's expiry when finite
	// (bearer credential `expires_at`; federated binding expiry), and the zero
	// time for an indefinite credential. The operator surfaces it as the ADR's
	// ahead-of-time expiry condition.
	CredentialExpiresAt time.Time
	// SchemaRevision is the project's monotonic key-catalogue revision, the
	// human-facing ordering the ADR pairs with the opaque token.
	SchemaRevision int64
	// Revision is the committed snapshot selected by this fetch.
	Revision int64
	// Keys is the delivered projection, empty when Current.
	Keys []DeliveredKey
	// PinnedRevision is non-zero when a durable pin selected the snapshot.
	PinnedRevision int64
	// PinExpired is a loud status condition only. Expiry ends retention
	// protection; it never changes delivery while the payload survives.
	PinExpired bool
	// CredentialID is the authenticated caller's immutable credential id. It is
	// returned on BOTH dispositions because clients bind it into snapshot AAD
	// and offline disclosure records rather than guessing their wire identity.
	CredentialID string
	// IssuedAt and SnapshotExpiresAt are server assertions bound into the
	// client's offline-snapshot AAD. They are present on both dispositions;
	// SnapshotExpiresAt is IssuedAt + delivery.SnapshotMaxAge.
	IssuedAt          time.Time
	SnapshotExpiresAt time.Time
	// FileTargetGeneration is the named file target's configuration
	// generation (#164), zero for an unbound caller.
	FileTargetGeneration int64
}

FetchResult is one machine fetch.

type FileTarget

type FileTarget = store.FileTarget

FileTarget intentionally shares a store-owned type with transport mapping. This sanctioned seam follows the system-architecture ADR; boundary_test.go enforces that handlers never import internal/store directly.

type FileTargetInput

type FileTargetInput struct {
	EnvironmentID    string
	Name             string
	ServiceAccountID string
	KeyIDs           []string
	KeySelection     AdapterKeySelection
}

FileTargetInput creates a file target.

type FileTargetKey

type FileTargetKey = store.FileTargetKey

FileTargetKey is the store's selected-key pair, shared the same way.

type FileTargetReport

type FileTargetReport = store.FileTargetReport

FileTargetReport is the store's report row, shared the same way.

type FileTargets

type FileTargets struct {
	DB  *store.DB
	Now func() time.Time
}

FileTargets owns file-target configuration.

func (*FileTargets) Create

func (s *FileTargets) Create(ctx context.Context, actor Actor, scope domain.Scope, in FileTargetInput) (FileTarget, error)

Create binds a workload service account to an environment and key set.

func (*FileTargets) Delete

func (s *FileTargets) Delete(ctx context.Context, actor Actor, scope domain.Scope, id string) error

Delete removes a file target. It refuses while the bound service account can still authenticate, because removing the binding would widen that account's delivery back to the whole environment.

func (*FileTargets) Get

func (s *FileTargets) Get(ctx context.Context, actor Actor, scope domain.Scope, id string) (FileTarget, error)

Get reads one file target with its resolved key selection.

func (*FileTargets) List

func (s *FileTargets) List(ctx context.Context, actor Actor, scope domain.Scope) ([]FileTarget, error)

List reads every file target of the project.

func (*FileTargets) UpdateKeys

func (s *FileTargets) UpdateKeys(ctx context.Context, actor Actor, scope domain.Scope, id string, expectedGeneration int64, keyIDs []string, selection AdapterKeySelection) (FileTarget, error)

UpdateKeys replaces the key selection under a generation compare-and-swap.

type Finding

type Finding struct {
	RuleID          string
	Surface         string
	Locator         string
	Acknowledgement string
}

Finding is one redacted scan result surfaced to the writer, everywhere it travels (wire, CLI, import output). It carries a rule id, the surface/ingress it fired on, an immutable locator, and — where an acknowledgement is possible (Surface-1 stage keep-as-config, Surface-2 override) — an opaque token. Banned by construction: matched text, offsets, length, excerpts (ADR §4).

type Folder

type Folder struct {
	ID        string
	OrgID     string
	ProjectID string
	Path      string
	CreatedAt time.Time
}

Folder is the service layer's folder: a project-scoped namespace and display grouping, and nothing else in v1.

type Folders

type Folders struct {
	DB *store.DB
	// Keyring and Scan: secret-scanning Surface-2 seam (#74). Folder path
	// segments are author-controlled declaration text.
	Keyring *crypto.Keyring
	Scan    *scanning.Ruleset
}

Folders owns the folder surface. Every method addresses PROJECT depth: the scope lattice has no folder level (the permission-model ADR forbids folder-scoped grants outright), so the folder id is an ordinary argument that can only resolve inside the project the proof already authorized.

func (*Folders) Create

func (s *Folders) Create(ctx context.Context, actor Actor, scope domain.Scope, path string, acks []string) (Folder, error)

func (*Folders) Delete

func (s *Folders) Delete(ctx context.Context, actor Actor, scope domain.Scope, id string) error

func (*Folders) Get

func (s *Folders) Get(ctx context.Context, actor Actor, scope domain.Scope, id string) (Folder, error)

func (*Folders) List

func (s *Folders) List(ctx context.Context, actor Actor, scope domain.Scope) ([]Folder, error)

func (*Folders) Rename

func (s *Folders) Rename(ctx context.Context, actor Actor, scope domain.Scope, id, path string, acks []string) (Folder, error)

Rename moves a folder to a new path. It renames exactly the row named: a folder is a flat namespace label in v1, not a tree node with children to carry along, so there is no cascade to get wrong.

type GrantOutcome

type GrantOutcome = api.GrantOutcome

func GrantCreated

func GrantCreated() GrantOutcome

func GrantOriginAdded

func GrantOriginAdded() GrantOutcome

func GrantUnchanged

func GrantUnchanged() GrantOutcome

type GrantResult

type GrantResult struct {
	GrantID string
	Outcome GrantOutcome
}

GrantResult reports what a create actually did, so callers can render the result without interpreting combinations of independently-set booleans.

type GrantSpec

type GrantSpec struct {
	Target     domain.PrincipalID
	Capability domain.Capability
	// Scope is where the grant applies. The zero Scope is instance scope.
	Scope domain.Scope
}

GrantSpec names one grant: who gets what, where.

type Grants

type Grants struct {
	DB *store.DB
	// Auth supplies the reauthentication conjunct a WIDENING grant on a
	// machine principal carries (#61). It is only consulted on that path: an
	// ordinary human grant has never required reauthentication and does not
	// start now.
	Auth *Auth
	Now  func() time.Time
	// contains filtered or unexported fields
}

Grants owns the grant surface. Every method opens one transaction, authorizes inside it, and performs the whole mutation — grant row, origin, session-generation advance and audit — before it commits. There is no authorization cache to invalidate, and this ticket keeps it that way.

func (*Grants) ApplyTemplate

func (s *Grants) ApplyTemplate(ctx context.Context, actor Actor, template domain.Template, target domain.PrincipalID, scope domain.Scope) ([]GrantResult, error)

ApplyTemplate expands a role template into independent grants at grant time. Nothing stores "Alice is a maintainer"; what is stored is the capabilities the template created, each on its own line and revocable on its own.

func (*Grants) BreakGlassGrant

func (s *Grants) BreakGlassGrant(ctx context.Context, spec GrantSpec) (GrantResult, error)

BreakGlassGrant issues a recovery grant under LOCAL HOST AUTHORITY — `hikyo admin grant`, on the server's own host, root key already loaded by the caller. It reaches no chokepoint operation and is, in the ADR's own words, "the only authorization path in the system not evaluated against a grant". There is deliberately no network route; the classification-totality invariant is what keeps that true.

It adds no attacker capability: host access plus the root key already means full control-plane compromise per the threat model. What it adds is a way out of the lockout invariant's one irrecoverable state — an instance with no `manage-members` holder — without an API that could be reached remotely.

The origin is `break-glass`, NOT `manual`. That is a reading of the ADR, not a convenience: `manual(granted_by)` names a granting principal whose own authority was evaluated, and this path has no granting principal at all. Recording it as manual would put a principal's name on an act no principal performed, and would make the row indistinguishable from an ordinary grant on the membership surface — which is exactly the thing an auditor is looking for after an incident.

func (*Grants) Create

func (s *Grants) Create(ctx context.Context, actor Actor, spec GrantSpec) (GrantResult, error)

Create grants one capability at one scope, deduplicating against the grantee's existing rows.

func (*Grants) InviteMember

func (s *Grants) InviteMember(ctx context.Context, actor Actor, spec InviteSpec) (InvitationResult, error)

InviteMember is the human-auth ADR's named account-creation path (#568): "accounts are created by invitation from a manage-members holder".

It is bootstrap minus the first-account check, under an authorization instead of host authority: create the principal and account, expand the optional template through the SAME writer applyOrgTemplate uses (so the grants, their events and §2.4's cure are indistinguishable from an ordinary template application), then mint a credential-establishment authority exactly as credential-reset does — same artifact, same lifetime, same establish endpoint — with `invitation` as the recorded issuer.

Everything commits in one transaction (ADR § Identity linking: "invitation consumption, account creation and any initial grants occur in ONE transaction"), so a username collision — the store's UNIQUE constraint, surfaced as domain.ErrConflict — leaves nothing behind.

func (*Grants) List

func (s *Grants) List(ctx context.Context, actor Actor, scope domain.Scope) ([]Membership, error)

List returns the membership surface for the addressed scope: every grant line inside the org (or at instance scope), narrowed to the addressed project when one is addressed.

Grants ABOVE the addressed scope are deliberately absent even though they reach it by inheritance. Showing an instance operator on an org's member list would invite revoking them from a page that has no authority to.

func (*Grants) Revoke

func (s *Grants) Revoke(ctx context.Context, actor Actor, spec GrantSpec) error

Revoke releases the calling surface's origins from one grant, and deletes the row when the last origin is gone — with the session-generation advance and the session-row deletion, in the same transaction. There is no authorization cache, so an in-flight authorization dies with the row.

type GroupPatchAddMembers

type GroupPatchAddMembers struct{ Members []string }

type GroupPatchClearExternalID

type GroupPatchClearExternalID struct{}

type GroupPatchClearMembers

type GroupPatchClearMembers struct{}

type GroupPatchCommand

type GroupPatchCommand interface {
	// contains filtered or unexported methods
}

GroupPatchCommand is the closed set of group PATCH mutations.

type GroupPatchRemoveMember

type GroupPatchRemoveMember struct{ Member string }

type GroupPatchReplaceMembers

type GroupPatchReplaceMembers struct{ Members []string }

type GroupPatchResult

type GroupPatchResult struct {
	Desired        DesiredGroup
	MembersTouched bool
}

GroupPatchResult is the desired final state plus the reconciliation effect that cannot be inferred from equality: reasserting an unchanged member set still rebuilds origins after restore.

func ReduceGroupPatch

func ReduceGroupPatch(current DesiredGroup, commands []GroupPatchCommand) (GroupPatchResult, error)

ReduceGroupPatch applies commands sequentially without mutating current.

type GroupPatchSetDisplayName

type GroupPatchSetDisplayName struct{ DisplayName string }

type GroupPatchSetExternalID

type GroupPatchSetExternalID struct{ ExternalID string }

type HandoffPurpose

type HandoffPurpose = authz.HandoffPurpose

HandoffPurpose is the closed two-member set, re-exported for the transport.

type HandoffRequest

type HandoffRequest struct {
	Origin        string
	RedirectURI   string
	PKCEChallenge string
	Purpose       HandoffPurpose
	SessionID     string
	ReauthIntent  *ReauthIntent
}

HandoffRequest opens a transaction. Purpose alone licenses an establishment; a step-up additionally binds the initiating session, the exact operation, and — where the operation is key-scoped — the environment and key set, so an elevated consent cannot be replayed against a different one.

type HandoffStart

type HandoffStart struct {
	HandoffID string
	State     string
	ExpiresAt time.Time
}

HandoffStart is what the shell needs to open the popup: the transaction's opaque state value, which crosses the front channel.

type HandoffView

type HandoffView struct {
	RequestingOrigin string
	Purpose          HandoffPurpose
	Operation        string
	EnvID            string
	KeySet           []string
	ExpiresAt        time.Time
}

HandoffView is the live transaction shape the remote's approve page reads. Establishments carry purpose, requesting origin and expiry; step-ups also carry the operation, environment and enumerated key set they were opened against. Identifiers only — never a value, a bearer or a verifier.

type Identities

type Identities struct {
	DB *store.DB
	// Auth supplies the reauthentication conjunct. Machines never
	// reauthenticate; the human minting one does.
	Auth *Auth
	Now  func() time.Time
}

Identities owns the machine-identity surface. Like every service here it opens one transaction, authorizes inside it, and performs the whole mutation before it commits.

func (*Identities) CreateServiceAccount

func (s *Identities) CreateServiceAccount(ctx context.Context, actor Actor, scope domain.Scope, name string, kind domain.PrincipalClass) (ServiceAccountView, error)

CreateServiceAccount creates a project-owned machine principal. `kind` is declared here and is immutable: there is no update path, because in-place widening of a class that N workloads already hold is what the ADR refuses.

Creation itself carries NO disclosure gate. A fresh service account holds no grants, so it reaches nothing; the gate fires when a grant lands on it (grants.go's widening rule) or when a credential is minted for it.

func (*Identities) DeleteServiceAccount

func (s *Identities) DeleteServiceAccount(ctx context.Context, actor Actor, scope domain.Scope, id string) error

DeleteServiceAccount revokes every credential and releases every grant in ONE transaction (#15's atomic revocation), then removes the principal.

It runs under the PLAIN capability with no disclosure gate and no reauthentication: this is the sharpest narrowing in the surface, and requiring `reveal` to deprovision a compromised workload would be a self-inflicted incident-response delay.

func (*Identities) ListCredentials

func (s *Identities) ListCredentials(ctx context.Context, actor Actor, scope domain.Scope, saID string) ([]CredentialView, error)

ListCredentials returns metadata only — prefix hint, kind, lifetime, expiry, creation and last use. Never the value: there is no field for it and no query that selects one.

func (*Identities) ListServiceAccounts

func (s *Identities) ListServiceAccounts(ctx context.Context, actor Actor, scope domain.Scope) ([]ServiceAccountView, error)

ListServiceAccounts lists a project's machine principals with their live credential counts. Listing is a narrowing-class operation: plain manage-identities, no disclosure gate.

func (*Identities) MintCredential

func (s *Identities) MintCredential(ctx context.Context, actor Actor, scope domain.Scope, saID string, req MintRequest) (MintResult, error)

MintCredential issues a bearer credential for one service account and returns its value EXACTLY ONCE.

This is the ADR's first authorization row, and the post-state phrasing is the load-bearing part: the disclosure conjunct ranges over every environment reachable in the RESULTING STATE, not over anything the mint adds — a mint adds no grants at all, so an "added environments" reading would require `reveal` on nothing and let a principal holding manage-identities and no reveal rotate a production credential and walk away with a live production-reading token.

Rotation is this call plus a revoke of the predecessor (ADR § Rotation: "mint a second credential, distribute it, revoke the first"). It is deliberately not one atomic verb: overlap is the intended steady state, so a mint that succeeds and a revoke that fails leaves the operator with two live credentials — the safe direction — rather than none.

func (*Identities) Policy

func (s *Identities) Policy(ctx context.Context, actor Actor) (PolicyView, error)

Policy reads the instance credential policy under `instance-config`.

func (*Identities) RevokeCredential

func (s *Identities) RevokeCredential(ctx context.Context, actor Actor, scope domain.Scope, saID, credentialID string) error

RevokeCredential kills one credential. It bites at the NEXT request: the liveness predicate is read in the authenticating transaction, uncached, so there is no window in which a revoked credential still reads anything.

Revoking one credential is NOT deprovisioning — grants are untouched and sibling credentials keep working — and it runs under the plain capability with no disclosure gate and no reauthentication.

func (*Identities) SetPolicy

func (s *Identities) SetPolicy(ctx context.Context, actor Actor, change PolicyChange) (PolicyResult, error)

SetPolicy moves the instance lifetime controls, enumerating every affected credential before it commits and clamping afterwards.

Clamping only ever moves an expiry DOWN. That asymmetry is what keeps `indefinite` a value rather than a number: raising the ceiling later cannot restore a window this clamp took away, and cannot turn a finite credential into an indefinite one however high it goes.

Withdrawing allow_indefinite converts every live indefinite credential to a finite one expiring at the new ceiling. It is not silent — the actor is shown the list and has to confirm it — and it is not a revocation: the credentials keep working until the ceiling, so the fleet has the same window to rotate that any other tightening gives it. Enumerating them and leaving them alone would report the control as withdrawn while unbounded credentials kept working, which is the control not being withdrawn.

type Identity

type Identity struct {
	Principal         domain.PrincipalID
	SessionID         string
	Artifact          Artifact
	Assurance         Assurance
	CreatedAt         time.Time
	IdleExpiresAt     time.Time
	AbsoluteExpiresAt time.Time
	// EnrolmentRequired mirrors the session flag (#760): whoami surfaces it so
	// the SPA renders the enrolment gate a flagged session is confined to.
	EnrolmentRequired bool
	// InstanceOperator is a disclosure-safe UI hint: the caller holds the
	// instance-config authority the operator-only reads (retention health,
	// update status) require. It is a reflection of the caller's own grant, not
	// an authorization — every one of those reads is still judged per request.
	InstanceOperator bool
	// InstanceAuditRead gates audit navigation independently of instance-config.
	// It reflects the caller's own grant; every read still authorizes normally.
	InstanceAuditRead bool
	// DeliveryReportGrant is a disclosure-safe UI hint: where the caller may
	// grant `report-delivery-status`. No human holds that atom, so every grant
	// of it is an unheld grant, and this is exactly the grant-unheld rule's
	// reach (mayGrantUnheld). A hint, not an authorization.
	DeliveryReportGrant UnheldGrantReach
	// DisplayName is the human account's chosen name, the same value login
	// returns, so a reloaded SPA can name its holder instead of showing a
	// principal id. Empty for principals that have no account row (a machine
	// bearer resolving its own identity).
	DisplayName string
}

Identity is a live, resolved caller.

type ImpactChange

type ImpactChange struct {
	VersionID      string
	KeyID          string
	Name           string
	Classification string
	Operation      string
	Status         string
	Before         *string
	After          *string
}

type ImpactEnvironment

type ImpactEnvironment struct {
	EnvironmentID  string
	BaseRevision   int64
	SchemaRevision int64
	Protected      bool
	Changes        []ImpactChange
}

type ImpactPreview

type ImpactPreview struct {
	Token        string
	Environments []ImpactEnvironment
}

ImpactPreview is the reveal-safe before/after plan shown before a restore is published. Secret-bearing rows never carry plaintext.

type ImportCandidate

type ImportCandidate struct {
	Name                   string
	IntendedClassification string
	IntendedType           string
}

ImportCandidate is one key phase 1 may declare. For an undeclared name the intended fields are bound into its token; for an existing name the current catalogue declaration remains authoritative.

type ImportEntry

type ImportEntry struct {
	Key   string
	Value string
}

ImportEntry is one key's imported plaintext.

type ImportOccurrence

type ImportOccurrence struct {
	KeyID          string
	Name           string
	Declared       bool
	Classification string
	Type           string
	// Set is the whole presence model: `set` or `absent`.
	Set bool
	// Token is the server-minted opaque occurrence token. Opaque means opaque:
	// a client copies it into the run manifest and never interprets it.
	Token string
}

ImportOccurrence is one key's phase-1 observation. It covers keys the project does NOT declare as well: an import proposes those, and phase 2 must be able to check they did not move either, so they carry a token binding the reviewed undeclared-to-declared class/type transition rather than no token.

type ImportOccurrenceRef

type ImportOccurrenceRef struct {
	Key         string
	Environment string
	Token       string
}

ImportOccurrenceRef is one reviewed occurrence from the manifest.

type ImportPrecondition

type ImportPrecondition struct {
	// DefinitionsRevision is phase 1 evidence only. Applying the reviewed
	// definitions bundle advances the project revision before phase 2, so
	// per-key occurrence tokens provide the enforceable freshness fence.
	DefinitionsRevision int64
	// Environments are every environment the manifest names. read(E) is
	// re-evaluated for each of them inside the import's own transaction, ON TOP
	// of the verb's own formula: a caller lacking it receives the plain
	// authorization failure and no precondition result.
	Environments []string
	// Occurrences are the reviewed (key, environment) tokens.
	Occurrences []ImportOccurrenceRef
}

ImportPrecondition is the run manifest's expected-state half, the one declared additive input `values import` gained.

type ImportPresence

type ImportPresence struct {
	Project             string
	Environment         string
	DefinitionsRevision int64
	Keys                []ImportOccurrence
}

ImportPresence is what phase 1 learned about one environment.

type ImportRequest

type ImportRequest struct {
	Entries []ImportEntry
	// Overwrite is the enumerated `set`-bucket consent. Skip-by-default
	// otherwise, which is what makes a re-run idempotent.
	Overwrite []string
	// Precondition is nil without `--manifest`, in which case `values import`
	// behaves exactly as locked.
	Precondition *ImportPrecondition
}

ImportRequest is one `values import` invocation against one environment.

type ImportResult

type ImportResult struct {
	Imported []string
	// Skipped are keys already `set` in the target environment that no
	// enumerated overwrite named. Listed by name, never silently dropped.
	Skipped []string
	// Findings are the Surface-1 warnings the imported CONFIG values produced
	// (#74, surface import_value), warn-not-block: the import succeeds and each
	// finding names its rule and key locator. No dismissal token here.
	Findings []Finding
}

ImportResult is what landed.

type InactiveCause

type InactiveCause string

InactiveCause is why a stored policy admits nobody (#579 d6/d11). The row stays; sign-ups refuse uniformly with the audited cause (#607, #608).

const (
	InactiveAuthorityLost       InactiveCause = "authority-lost"
	InactiveAuthorityUnassigned InactiveCause = "authority-unassigned"
	InactivePrecondition        InactiveCause = "precondition"
)

type InstanceMail

type InstanceMail struct {
	DB      *store.DB
	Auth    *Auth
	Capture func(context.Context) (*runtimeconfig.Bundle, error)
}

InstanceMail uses the active runtime bundle, including managed-source fences. Test sends share the self-configuration test's installation-wide lease/bucket.

func (*InstanceMail) Configured

func (s *InstanceMail) Configured(ctx context.Context, actor Actor) (bool, error)

func (*InstanceMail) Test

func (s *InstanceMail) Test(ctx context.Context, actor Actor, to, proof string) error

type InvitationResult

type InvitationResult struct {
	PrincipalID   domain.PrincipalID
	AccountID     string
	Authority     string
	AuthorityID   string
	ExpiresAt     time.Time
	GrantsCreated int
}

InvitationResult carries the one-time authority out to the caller. The value is in memory only and is never re-displayed: if it lapses, reset the credential (a second invitation of the same username is a conflict).

type InviteSpec

type InviteSpec struct {
	// Scope is the organisation invited into; the zero Scope is instance scope.
	Scope       domain.Scope
	Username    string
	DisplayName string
	// Template is optional: "" invites an account that can sign in and see
	// nothing — the human-auth ADR's "provisioning and authorizing are
	// separate acts" default.
	Template domain.Template
	// Delivery names how the caller hands the authority over. It is recorded
	// in the mint event because delivery mode IS the security property.
	Delivery string
}

InviteSpec is one invitation (#568): WHERE (an organisation, or the instance), WHO (the local login handle) and, optionally, WHAT they start with (a role template expanded at that scope).

type IssueSSHCertificateRequest

type IssueSSHCertificateRequest struct {
	ProfileID       string
	PublicKey       string
	KeyAlgorithm    string
	Principals      []string
	SourceAddresses []string
	Extensions      []string
	TTLSeconds      int64
}

IssueSSHCertificateRequest asks for one certificate. Exactly one of PublicKey (sign the caller's key) or a generated key (PublicKey empty, KeyAlgorithm naming the algorithm, default ed25519) applies. Extensions nil takes the profile's default; an empty non-nil slice asks for none.

type IssuerRequest

type IssuerRequest struct {
	Issuer           string
	Type             domain.IssuerType
	KeySource        jwkssource.KeySource
	CABundlePEM      string
	RefusedAudiences []string
}

IssuerRequest configures one issuer.

type IssuerView

type IssuerView struct {
	ID               string
	Issuer           string
	Type             domain.IssuerType
	KeySource        jwkssource.KeySource
	CABundlePEM      string
	RefusedAudiences []string
	CreatedAt        time.Time
	CreatedBy        domain.PrincipalID
	UpdatedAt        time.Time
	UpdatedBy        domain.PrincipalID
	// Bindings is how many bindings name this issuer, live or historical, so an
	// operator can see the blast radius of a delete before attempting one -- and
	// a delete is refused while any remain, including revoked ones, because
	// erasing the issuer a past binding trusted erases what it trusted.
	Bindings int64
}

IssuerView is one issuer configuration. The API renders only KeySource.Mode; the static document remains write-only on the wire.

type Key

type Key struct {
	ID              string
	OrgID           string
	ProjectID       string
	Name            string
	FolderPath      string
	Classification  string
	Description     string
	Deprecated      bool
	DeprecationNote string
	Declaration     schema.Declaration
	Presence        schema.PresenceRules
	GroupID         string
	CreatedAt       time.Time
}

Key is the service layer's declared key. Declaration and Presence are the parsed forms: the store holds the canonical JSON, and exactly one place (this one) turns it back into rules, so there is no second interpreter to disagree with the first.

type KeyDeclarationUpdate

type KeyDeclarationUpdate struct {
	Declaration schema.Declaration
	Presence    schema.PresenceRules
}

KeyDeclarationUpdate is the semantic update: the value-dependent rules and the presence rules, replaced together.

type KeyDeletion

type KeyDeletion struct {
	Name   string   `json:"name"`
	LiveIn []string `json:"live_in"`
}

KeyDeletion is one deleted key with the environments that still hold a live value for it — the concrete impact the plan preview renders.

type KeyGroupView

type KeyGroupView struct {
	ID        string
	OrgID     string
	ProjectID string
	Name      string
	Members   []string // key names, sorted
	Inert     bool
	CreatedAt time.Time
}

KeyGroupView is a group with the two derived facts a reader needs: who is in it, and whether it is inert. A group left with fewer than two members couples nothing — the ADR calls that state inert and requires it flagged, rather than deleted behind the operator's back.

type KeyGroups

type KeyGroups struct {
	DB       *store.DB
	Keyring  *crypto.Keyring
	Advisory *Advisory
	Budget   *Budget
	// Scan: secret-scanning Surface-2 seam (#74). Group names are
	// author-controlled declaration text.
	Scan *scanning.Ruleset
}

KeyGroups owns the group surface, likewise at project depth.

func (*KeyGroups) Create

func (s *KeyGroups) Create(ctx context.Context, actor Actor, scope domain.Scope, name string, acks []string) (KeyGroupView, error)

Create declares a key group. Groups exist as vocabulary here; the co-publish closure and the all-or-none presence evaluation that give them teeth are publish-time (#51).

func (*KeyGroups) Delete

func (s *KeyGroups) Delete(ctx context.Context, actor Actor, scope domain.Scope, id string) error

Delete dissolves a group and releases its members. It never deletes the keys it coupled: a group is a coupling, and removing a coupling is not removing what it coupled.

func (*KeyGroups) Get

func (s *KeyGroups) Get(ctx context.Context, actor Actor, scope domain.Scope, id string) (KeyGroupView, error)

func (*KeyGroups) List

func (s *KeyGroups) List(ctx context.Context, actor Actor, scope domain.Scope) ([]KeyGroupView, error)

func (*KeyGroups) Rename

func (s *KeyGroups) Rename(ctx context.Context, actor Actor, scope domain.Scope, id, name string, acks []string) (KeyGroupView, error)

Rename changes a group's label. A group name is never delivered, so it materializes nothing — but a group name IS definitions-bundle desired state (#70), so the rename advances the definitions revision so a bundle base can detect it.

type KeyMetadataUpdate

type KeyMetadataUpdate struct {
	FolderPath      *string
	Description     *string
	Deprecated      *bool
	DeprecationNote *string
	// ConfirmWidening names the people a folder move gives access to through
	// their member access rules (ADR D9). A widening move commits only when it
	// names exactly that set; a move that widens nothing ignores it.
	ConfirmWidening []domain.PrincipalID
}

KeyMetadataUpdate is the NON-semantic update. It deliberately has no classification field and no rule field: the schema-model ADR exempts exactly these four from per-environment publish authorization because they cannot change what any environment delivers, and a fifth field here would silently widen that exemption.

Every field is a POINTER because this is a PATCH: nil means "leave it alone", and the update is merged over the stored row inside the transaction. With plain values an absent `folder_path` would arrive as "" and silently move the key to the catalogue root — a caller who set only `--description` would lose the folder, the deprecation flag and the note in one request. That is the silent fallback this project refuses, and a PATCH whose contract declares its members optional is exactly where it hides.

type KeySpec

type KeySpec struct {
	Name            string
	FolderPath      string
	Classification  string
	Description     string
	Deprecated      bool
	DeprecationNote string
	Declaration     schema.Declaration
	Presence        schema.PresenceRules
	GroupID         string
}

KeySpec is a key creation. It carries no id (server-minted, immutable) and no schema revision (the project's, not the key's).

type Keys

type Keys struct {
	DB *store.DB
	// Owner policy bounds project overrides; zero uses documented defaults.
	DefaultKeysPerProject int
	MaxKeysPerProject     int
	// Keyring materializes the semantic schema fan-out's snapshots. Nil
	// refuses any semantic change in a project that has environments, which is
	// the fail-closed answer: a schema change that cannot materialize is a
	// schema change whose environments would keep delivering under a revision
	// they were never validated at.
	Keyring  *crypto.Keyring
	Advisory *Advisory
	// Budget applies the § 151 schema-revision rate limit (60/h per project) to
	// every semantic schema mutation, via prepareSchemaPublish. Nil disables it.
	Budget *Budget
	// Scan is the secret-scanning ruleset (#74). Surface-2 declaration ingresses
	// (key create/rename/metadata/declaration edits) block on a finding; the
	// secret→config declassification leg of Reclassify is a Surface-1 warn.
	Scan *scanning.Ruleset
}

Keys owns the key surface. Every method addresses PROJECT depth: a key is declared once per project, and the scope lattice has no key level.

func (*Keys) Create

func (s *Keys) Create(ctx context.Context, actor Actor, scope domain.Scope, spec KeySpec, acks []string) (Key, error)

Create declares a key. Typing a key name that does not exist is a key CREATION — an explicit act, never a silent value write (ADR § Closed schema): that is the whole reason a typo'd `DATBASE_URL` is answerable at all.

func (*Keys) Delete

func (s *Keys) Delete(ctx context.Context, actor Actor, scope domain.Scope, id string) error

Delete removes a key from the catalogue. Its explicit presence rows go with it and it drops out of its group; the group itself survives, possibly inert.

func (*Keys) Get

func (s *Keys) Get(ctx context.Context, actor Actor, scope domain.Scope, id string) (Key, error)

Get reads one key with its presence rules.

func (*Keys) List

func (s *Keys) List(ctx context.Context, actor Actor, scope domain.Scope) ([]Key, int64, error)

List returns the project's key catalogue and the revision it is at. The revision rides along because it is the thing #50 and #51 pin, so a reader that acted on this list can say which schema it saw.

func (*Keys) ListPage

func (s *Keys) ListPage(ctx context.Context, actor Actor, scope domain.Scope, afterName string, limit int) ([]Key, int64, error)

ListPage is the bounded keyset read behind hikyo_list_definitions. The stable order is the UNIQUE key name; afterName is "" for the first page. Presence is resolved per page key, never by listing the project's presence rows. The schema revision rides along exactly as the unbounded List returns it.

func (*Keys) Reclassify

func (s *Keys) Reclassify(ctx context.Context, actor Actor, scope domain.Scope, id, classification string) (Key, []Finding, error)

Reclassify is the reclassification CEREMONY (mvp-boundary C1). It is a distinct operation and the only path that writes the classification column: an ordinary update carries no classification field, so there is no way to change one without meeting the gates and the audit below.

Declassification (`secret` → `config`) requires current `reveal`, because after it the value is readable under ordinary environment read — you must be able to see a secret in order to stop it being one. Tightening (`config` → `secret`) does not, and cannot un-disclose what was already served as config; the advisory belongs to the UI (#56+).

func (*Keys) Rename

func (s *Keys) Rename(ctx context.Context, actor Actor, scope domain.Scope, id, name string, acks []string) (Key, error)

Rename changes the key's mutable label. It IS a content-affecting schema change — the delivered payload's key set moves — so it advances the schema revision, unlike the hierarchy renames, which move a label nothing is delivered under.

func (*Keys) SetGroup

func (s *Keys) SetGroup(ctx context.Context, actor Actor, scope domain.Scope, id, groupID string) (Key, error)

SetGroup moves a key into a group, or out of every group when groupID is "". A key belongs to at most one group, so this is a set rather than an append — multi-membership would make co-publish closure transitive across groups, and selecting one pending change could then drag in a chain the publisher never previewed.

func (*Keys) UpdateDeclaration

func (s *Keys) UpdateDeclaration(ctx context.Context, actor Actor, scope domain.Scope, id string, u KeyDeclarationUpdate, acks []string) (Key, error)

UpdateDeclaration replaces the value-dependent rules and the presence rules.

THE ORDER IN THIS METHOD IS THE SECURITY PROPERTY. The schema-model ADR's load-bearing rule: changing a value-dependent rule on a `secret` key is a disclosure, because the result bit itself is the leak — a principal holding definitions-edit but not `reveal` can set `pattern: "^A"`, watch the publish abort, and bisect the plaintext one predicate at a time. So the gate runs BEFORE the new declaration is compiled or evaluated in any way: the operation is rejected without evaluating, because timing and abort/success are themselves the channel.

The gate is unconditional on whether any value exists. Conditioning it on stored values would add a query and a time-of-check/time-of-use window for no gain — and this slice has no value rows at all, so a conditional gate would be dead until #50 and then wrong.

func (*Keys) UpdateMetadata

func (s *Keys) UpdateMetadata(ctx context.Context, actor Actor, scope domain.Scope, id string, m KeyMetadataUpdate, acks []string) (Key, error)

UpdateMetadata writes the non-semantic fields. No reveal gate and no publish fan-out: these cannot change what any environment delivers or whether it validates, so there is nothing to re-materialize and nothing to disclose. It DOES advance the schema revision (#70): folder path and deprecation are definitions-bundle desired state, and a revision used as a bundle base must be able to detect they moved.

type LandingKind

type LandingKind string

LandingKind is where a sign-up arrives (spec 2.1). An org policy lands org-template; an instance policy lands none or fresh-org.

const (
	LandingOrgTemplate LandingKind = "org-template"
	LandingNone        LandingKind = "none"
	LandingFreshOrg    LandingKind = "fresh-org"
)

type LastApply

type LastApply struct {
	PlanID    string
	AppliedAt time.Time
	AppliedBy string
	Commit    string
	Ref       string
	Actor     string
	Revision  int64
}

LastApply is the last-applied provenance record the settings view surfaces.

type LoginChallengeIssued

type LoginChallengeIssued struct {
	ID        string
	ExpiresAt time.Time
	Factors   []string
}

LoginChallengeIssued is the 202 outcome of a browser password login on an account with an enrolled factor: the continuation handle, its expiry, and the factor classes that can satisfy it. No session exists yet (#760).

type LoginResult

type LoginResult struct {
	SessionToken string
	SessionID    string
	Artifact     Artifact
	CreatedAt    time.Time
	IdleExpires  time.Time
	AbsExpires   time.Time
	Principal    domain.PrincipalID
	AccountID    string
	DisplayName  string
	Assurance    Assurance
	// CSRFToken is the synchronizer token for a browser session, returned once
	// at mint (A9). Empty for CLI sessions.
	CSRFToken string
	// Challenge is set instead of a session when a browser password login lands
	// on an account with an enrolled factor (#760): no session and no cookie
	// exist until a finish op consumes the challenge. When it is non-nil every
	// session field above is empty.
	Challenge *LoginChallengeIssued
}

LoginResult is a freshly minted session. SessionToken is returned exactly once, to exactly one caller.

type MCPAdmission

type MCPAdmission struct {
	DB *store.DB
}

MCPAdmission performs the shared phase-1 rate and concurrency admission. It first resolves and authorizes inside a read transaction, so guessed scope ids cannot occupy tenant capacity. The actual page service repeats both checks in its own transaction after admission; the principal id returned by the first transaction is only a limiter key and never authorization state.

func (*MCPAdmission) Acquire

func (s *MCPAdmission) Acquire(ctx context.Context, actor Actor, op authz.Operation, scope domain.Scope) (func() error, error)

Acquire authorizes one closed MCP operation (the phase-1 reads and the mcp-write stage and validate operations), then atomically charges its datastore-coordinated token bucket and claims 4/principal, 8/org, and 64/instance capacity. Release is synchronous and safe to call once.

type MachineRevealSettings

type MachineRevealSettings struct {
	Enabled bool
}

MachineRevealSettings is the per-project machine-reveal opt-in on the wire.

type MasterKeyRotation

type MasterKeyRotation struct {
	Version uint32
}

MasterKeyRotation is one `rotate-master-key`: the new master version.

type Membership

type Membership struct {
	PrincipalName string
	GrantID       string
	Principal     domain.PrincipalID
	Capability    domain.Capability
	Scope         domain.Scope
	Origins       []authz.Origin
	CreatedAt     time.Time
}

Membership is one capability line on the membership surface: a principal, a capability, the scope it was granted at, and the origins holding it.

type MintConnectionResult

type MintConnectionResult struct {
	Value      string
	Connection ConnectionView
	Clamped    bool
}

MintConnectionResult carries the one and only disclosure of the value.

type MintDeveloperCredentialRequest

type MintDeveloperCredentialRequest struct {
	Lifetime                time.Duration
	ConsentCurrentAndFuture bool
	KeyIDs                  []string
}

type MintLeaseRequest

type MintLeaseRequest struct {
	ProviderID    string
	MaxTTLSeconds int64
}

type MintLeaseResult

type MintLeaseResult struct {
	Lease     store.DynamicLease
	Username  string
	Password  string
	ExpiresAt time.Time
}

MintLeaseResult carries the display-once secret exactly once.

type MintRequest

type MintRequest struct {
	// Indefinite selects the DISTINCT typed lifetime. It is a separate field
	// from Lifetime rather than a sentinel duration, because `indefinite` is
	// a value and must be unreachable by raising any ceiling.
	Indefinite bool
	// Lifetime is the requested finite duration; zero means the default.
	Lifetime time.Duration
}

MintRequest names the lifetime a caller wants. The zero value asks for the finite default, which is the ADR's "the easy path is bounded".

type MintResult

type MintResult struct {
	Value      string
	Credential CredentialView
	// Clamped reports that the instance ceiling shortened what was asked
	// for, so the caller can say so rather than let the operator discover it
	// when the credential dies early.
	Clamped bool
}

MintResult carries the credential value EXACTLY ONCE, to exactly one caller. Nothing persists it and no read path returns it.

type MintedDeveloperCredential

type MintedDeveloperCredential struct {
	Credential DeveloperCredential
	Value      string
}

type MoveWideningError

type MoveWideningError struct {
	KeyID      string
	Count      int
	Principals []domain.PrincipalID
	Gains      []WideningGain
}

MoveWideningError refuses a key folder move that gives people access through their rules without an explicit confirmation naming exactly them (ADR D9). It is a conflict: the caller is authorized, the resulting state needs their consent.

Who gains is administrative information: Principals and Gains are set only when the caller holds legacy manage-members on the project (the audience of the rule listing). Anyone else learns only Count, and cannot confirm the move.

func (*MoveWideningError) Error

func (e *MoveWideningError) Error() string

func (*MoveWideningError) SafeDetail

func (e *MoveWideningError) SafeDetail() string

SafeDetail names the principals only when they were disclosed to the caller.

func (*MoveWideningError) Unwrap

func (e *MoveWideningError) Unwrap() error

func (*MoveWideningError) Widening

func (e *MoveWideningError) Widening() (count int, gains []WideningGain)

Widening is the structured half of the refusal the transport renders; nil unless the gainers were disclosed.

type MyOrg

type MyOrg struct {
	ID   string
	Name string
}

MyOrg is an organisation as a navigation destination — identity only. The rail needs a name and a route; `metadata` and `active` are operator-set state and belong to Get, which authorizes.

type OAuth2ProviderInput

type OAuth2ProviderInput struct {
	Profile            string
	DisplayName        string
	Issuer             string
	ClientID           string
	ClientSecret       string
	Enabled            bool
	CreateOnly         bool
	ExpectedRowVersion *int64
}

OAuth2ProviderInput is a create-or-update request body.

type OAuth2ProviderView

type OAuth2ProviderView struct {
	Profile     string
	Slug        string
	DisplayName string
	Issuer      string
	ClientID    string
	RedirectURI string
	Enabled     bool
	RowVersion  int64
}

OAuth2ProviderView is a provider as returned to an administrator. The client secret never leaves the server, so it is absent here.

type OAuth2Providers

type OAuth2Providers struct {
	DB      *store.DB
	Keyring *crypto.Keyring
	// ExternalOrigin is the instance's public origin, used to build the
	// per-provider redirect URI (A1). Never derived from a request header.
	ExternalOrigin string
	Now            func() time.Time
}

func (*OAuth2Providers) Delete

func (s *OAuth2Providers) Delete(ctx context.Context, actor Actor, slug string) error

Delete removes a provider and sweeps its federated sessions (A4). Its transaction rows and federated sessions cascade on the FK (A14); the sweep runs after the provider row is locked so the count is accurate and no mint can race the delete.

func (*OAuth2Providers) Get

func (s *OAuth2Providers) Get(ctx context.Context, actor Actor, slug string) (OAuth2ProviderView, error)

Get returns one provider by slug.

func (*OAuth2Providers) List

func (s *OAuth2Providers) List(ctx context.Context, actor Actor) ([]OAuth2ProviderView, error)

List returns every configured provider.

func (*OAuth2Providers) Put

Put validates the closed profile locally, then seals configuration. No discovery runs.

type OIDCCallbackResult

type OIDCCallbackResult struct {
	Login   LoginResult
	Purpose string
	State   string
	Browser bool
}

OIDCCallbackResult carries the freshly minted or rotated session on success.

type OIDCStartResult

type OIDCStartResult struct {
	AuthURL       string
	State         string
	BindingCookie string // "ob" artifact for an anonymous login; empty for a session-bound tx
	Purpose       string
}

OIDCStartResult is the authorization URL plus the artifacts the transport carries: the state value (used to derive the per-transaction binding-cookie name, A16) and, for an anonymous login, the browser-binding cookie value the callback must present (A2).

type OfflineRecord

type OfflineRecord struct {
	RecordID        string
	KeyID           string
	KeyName         string
	Classification  string
	OccurredAt      time.Time
	CredentialID    string
	Generation      string
	ServedFrom      time.Time
	SnapshotReceipt string
}

OfflineRecord is one client-durable disclosure record produced before an offline snapshot released plaintext.

type Org

type Org struct {
	ID        string
	Name      string
	Active    bool
	Metadata  json.RawMessage
	CreatedAt time.Time
	// Origin is `manual` or `registration` (#585 d8); RegistrationPolicyID
	// names the minting policy of a self-served org, else empty.
	Origin               string
	RegistrationPolicyID string
}

Org is the service layer's organisation. It is a distinct type from the store row on purpose: internal/store is importable only by this package, so a transport that returned store rows would either violate that boundary or force it open. Field names match the store row, which keeps the conversion a copy rather than a translation.

type Orgs

type Orgs struct {
	DB *store.DB
}

Orgs is the organisation surface. Creation and enumeration are instance-scoped operator work; every by-id operation is tenant-scoped at org depth, so an org the caller may not reach is indistinguishable from one that does not exist.

func (*Orgs) Count

func (s *Orgs) Count(ctx context.Context, actor Actor) (int64, error)

func (*Orgs) Create

func (s *Orgs) Create(ctx context.Context, actor Actor, name string, active bool, metadata json.RawMessage) (Org, error)

Create publishes a new org and applies the org-admin template to its creator through one transactional boundary. Creation requires both instance-config and instance manage-members: without the second conjunct, an instance-config holder could create a tenant and self-escalate into its secrets. The grant invalidates the creator's sessions like every privilege increase; the new authority becomes usable on their next login.

Org names and metadata are NOT secret-scanned (#74, ADR §2 Surface 2): the scan surface is "any string in the DEFINITIONS MODEL", and an org is not bundle content — §5 gives declaration events project scope, so an org-scoped scanning event cannot exist compliantly (OpOrgCreate's instance proof cannot even write a tenant scanning event). Folder/environment/group/key fields — the bundle content the ADR actually enumerates — are scanned; org and project names are not. Decision recorded in docs/handoff/74-secret-scanning.md.

func (*Orgs) Delete

func (s *Orgs) Delete(ctx context.Context, actor Actor, org domain.OrgID) error

Delete removes an org. Authority scoped inside the org is part of the org, so it is released in the same transaction; otherwise the creator-admin grants installed by Create would make even a brand-new org undeletable. Other descendants still do not cascade: a project (or any content below it) keeps the ancestry constraint live and the whole transaction rolls back.

func (*Orgs) Get

func (s *Orgs) Get(ctx context.Context, actor Actor, org domain.OrgID) (Org, error)

Get reads one org. It is a proof-scoped pure read at org depth, so it emits no event of its own: the trail would only duplicate what the read returned, which is the exact shape the audit model's default-deny permit accepts.

func (*Orgs) List

func (s *Orgs) List(ctx context.Context, actor Actor) ([]Org, error)

List is the instance-scoped enumeration of every org, and therefore itself audited (the audit model's default-deny rule refuses `audited: none` to instance-class operations). The event commits with the read, which is why this runs in a write transaction: an operator read without its durable record does not complete.

func (*Orgs) ListMine

func (s *Orgs) ListMine(ctx context.Context, actor Actor) ([]MyOrg, error)

ListMine is the navigation surface: exactly the organisations the caller's own grants name, at org scope or below.

It is NOT List with a filter, and the difference is the whole point. List enumerates every org on the instance under `instance-config`, which the human-auth ADR makes MFA-mandatory — correct for operator work, absurd in front of a sidebar. This projects the caller's own grant rows, so there is no capability to require (holding a grant IS the predicate, and requiring one would be circular) and nothing to leak: every row it can return names an org the caller already holds authority in.

It therefore emits no audit event, for the same reason `whoami` and `listIdentities` emit none. The audit model's default-deny governs REGISTRY OPERATIONS — `audited: none` is a permit an operation must earn. This is not an operation: it reaches no chokepoint, mutates nothing, and reads only the caller's own grant projection. Recording "a principal looked at their own sidebar" on every page load would add a row per boot that no investigation could ever act on, which is noise the trail has to carry forever.

Runs in a read transaction: nothing here writes.

func (*Orgs) Rename

func (s *Orgs) Rename(ctx context.Context, actor Actor, org domain.OrgID, name string) (Org, error)

Rename changes the org's mutable name. The read that produces the previous name for the trail runs inside the same transaction as the write, so the recorded transition is the one that actually happened.

type OriginView

type OriginView struct {
	Origin    string
	CreatedAt time.Time
	CreatedBy domain.PrincipalID
}

OriginView is one allowlist entry as the transport sees it. The service owns this shape rather than handing out the store's carrier: the import-boundary rule is that only this package names resolution-surface types, and a transport that could name one could build one.

type PKI

type PKI struct {
	DB      *store.DB
	Auth    *Auth
	Keyring *wencrypto.Keyring
	Budget  *Budget
	Runtime *store.PKIRuntime
	// IssuingDeadline bounds the window between reserving a serial and
	// recording the signed leaf. A row still `issuing` past it becomes
	// `unknown` and is published on the CRL.
	IssuingDeadline time.Duration
	Now             func() time.Time
}

PKI owns the private-PKI surface (#154, docs/adr/pki.md): instance CA issuers (sealed, non-exportable, versioned for overlap rotation), closed narrowing-only certificate profiles, and environment-scoped certificate issuance, renewal and revocation. CA private keys never cross this type's boundary: views carry certificates and fingerprints only.

func (*PKI) BindProfile

func (s *PKI) BindProfile(ctx context.Context, actor Actor, name, orgID, projectID, environmentID string) (PKIProfileView, error)

BindProfile reaches a profile into one project, or one environment of it.

func (*PKI) BoundProfiles

func (s *PKI) BoundProfiles(ctx context.Context, actor Actor, scope domain.Scope) ([]PKIBoundProfileView, error)

BoundProfiles returns policies bound to the authorized environment or its whole project, without exposing bindings. It requires a complete environment scope and propagates authorization, storage, and policy decoding errors.

func (*PKI) CertificateCRL

func (s *PKI) CertificateCRL(ctx context.Context, actor Actor, scope domain.Scope, certificateID string) ([]byte, error)

CertificateCRL returns the CRL published by the issuer version that signed the certificate: the list a relying party checks that leaf against.

func (*PKI) CreateIssuer

func (s *PKI) CreateIssuer(ctx context.Context, actor Actor, req PKIIssuerRequest) (PKIIssuerResult, error)

CreateIssuer creates version 1 of a new named issuer: an evaluation root, a Hikyo-signed intermediate (ParentName set), a pending intermediate awaiting an offline-signed certificate (no ParentName), or an imported CA.

func (*PKI) CreateProfile

func (s *PKI) CreateProfile(ctx context.Context, actor Actor, name string, policy pki.Policy) (PKIProfileView, error)

CreateProfile validates and stores a normalized policy with no bindings, requiring every named issuer to exist, and audits the creation. Invalid input wraps domain.ErrInvalid; an existing name returns ErrPKIProfileExists. Authorization, storage, and audit errors are propagated.

func (*PKI) DeleteProfile

func (s *PKI) DeleteProfile(ctx context.Context, actor Actor, name string) error

DeleteProfile removes a profile and its bindings. Certificates it issued keep their records (they name the profile by snapshot) but can no longer be renewed through it: removal is a narrowing.

func (*PKI) InstallIssuerCertificate

func (s *PKI) InstallIssuerCertificate(ctx context.Context, actor Actor, name, certificatePEM, chainPEM string) (PKIIssuerView, error)

InstallIssuerCertificate activates a pending version with the certificate an offline root signed for its CSR. The certificate must carry the pending key, be a CA with certificate and CRL signing, and verify against the supplied chain (the offline root last).

func (*PKI) IssueCertificate

func (s *PKI) IssueCertificate(ctx context.Context, actor Actor, scope domain.Scope, req CertificateIssueRequest) (CertificateIssueResult, error)

IssueCertificate issues one leaf in an environment through a bound profile (ADR D6), using exactly one of a CSR or a generated key. Names come from req, not the CSR. A zero TTL uses the profile default. A generated private key is returned only on success, never stored, and must be zeroed by the caller. Validation, authorization, budget, storage, and signing errors reach the caller. Errors after reservation can leave a failed or unresolved issuance record; an error does not imply that no record was created.

func (*PKI) IssuerCRL

func (s *PKI) IssuerCRL(ctx context.Context, actor Actor, name string, version int64) ([]byte, error)

IssuerCRL returns the stored DER CRL of one issuer version. A nonpositive version selects the newest version with a published CRL, regardless of lifecycle state. Missing issuers, versions, or CRLs return a not-found error. The read is authorized and audited and touches no key material.

func (*PKI) ListCertificates

func (s *PKI) ListCertificates(ctx context.Context, actor Actor, scope domain.Scope) ([]CertificateView, error)

ListCertificates returns up to 500 certificates in the authorized environment, newest first, with public issuer chains. It requires a complete environment scope and propagates authorization and storage errors.

func (*PKI) ListIssuers

func (s *PKI) ListIssuers(ctx context.Context, actor Actor) ([]PKIIssuerView, error)

ListIssuers returns every issuer version, ordered by name then version.

func (*PKI) ListProfiles

func (s *PKI) ListProfiles(ctx context.Context, actor Actor) ([]PKIProfileView, error)

ListProfiles returns profiles ordered by name, including policy and bindings, and audits the inventory read. Authorization, storage, policy decoding, and audit errors are returned; results are usable only when err is nil.

func (*PKI) PublishIssuerCRL

func (s *PKI) PublishIssuerCRL(ctx context.Context, actor Actor, name string, version int64) (PKIIssuerView, error)

PublishIssuerCRL signs and stores a fresh CRL for one version now, instead of waiting for the worker (after revocations an operator wants out at once).

func (*PKI) ReleaseIssuerHold

func (s *PKI) ReleaseIssuerHold(ctx context.Context, actor Actor, name string) ([]PKIIssuerView, error)

ReleaseIssuerHold lifts the restore hold on every version of a named issuer, after the operator has re-applied revocations made since the backup.

func (*PKI) RenewCertificate

func (s *PKI) RenewCertificate(ctx context.Context, actor Actor, scope domain.Scope, certificateID string) (CertificateView, error)

RenewCertificate re-signs a certificate's public key inside its profile's renewal window, against the CURRENT profile and the CURRENT active issuer version (overlap rotation). A second renewal of the same certificate returns its successor instead of signing again.

func (*PKI) RetireIssuer

func (s *PKI) RetireIssuer(ctx context.Context, actor Actor, name string, version int64) (PKIIssuerView, error)

RetireIssuer ends an overlap: the version stops signing CRLs and its key is destroyed. It refuses while unexpired leaves or child CAs need CRL coverage.

func (*PKI) RevokeCertificate

func (s *PKI) RevokeCertificate(ctx context.Context, actor Actor, scope domain.Scope, certificateID, reason string) (CertificateView, error)

RevokeCertificate revokes a leaf with a caller-chosen RFC 5280 reason. It never re-checks that the profile still permits the names: revocation is the fail-safe direction. Revoking a revoked certificate returns it unchanged. If neither SAN metadata nor its signed leaf can render the response, the authorized revocation still commits; the returned error says it is revoked.

func (*PKI) RevokeIssuer

func (s *PKI) RevokeIssuer(ctx context.Context, actor Actor, name string, version int64) (PKIIssuerView, error)

RevokeIssuer is the compromise response (ADR D3): terminal, key destroyed, every live leaf of the version revoked with reason ca-compromise.

func (*PKI) RotateIssuer

func (s *PKI) RotateIssuer(ctx context.Context, actor Actor, name string, req PKIIssuerRequest) (PKIIssuerResult, error)

RotateIssuer creates version N+1 of a named issuer (ADR D3 overlap rotation). A root or Hikyo-signed intermediate activates at once and moves version N to `retiring` in the same transaction; an offline-signed intermediate becomes `pending` with a CSR, and version N stays active until the new certificate is installed; an imported issuer rotates to the newly imported material.

func (*PKI) RunPKISweep

func (s *PKI) RunPKISweep(ctx context.Context) (bool, error)

RunPKISweep is one tick of the private-PKI worker (ADR D6-D8), run on every node: stale `issuing` rows become `unknown`, expired leaves become `expired`, and every issuer version whose CRL is due gets a freshly signed one. Every write is a CAS, so concurrent nodes never double-apply. It reports whether it did any work, so the caller can loop without sleeping while a backlog drains. Sweep errors stop the tick; CRL publication errors do not prevent attempts for other candidates, and the first is returned alongside whether any work succeeded.

func (*PKI) ShowCertificate

func (s *PKI) ShowCertificate(ctx context.Context, actor Actor, scope domain.Scope, certificateID string) (CertificateView, error)

ShowCertificate returns one certificate and its public issuer chain within the authorized environment. Missing or out-of-scope records return not found; scope validation, authorization, and storage errors are propagated.

func (*PKI) ShowIssuer

func (s *PKI) ShowIssuer(ctx context.Context, actor Actor, name string) ([]PKIIssuerView, error)

ShowIssuer returns every version of one named issuer.

func (*PKI) ShowProfile

func (s *PKI) ShowProfile(ctx context.Context, actor Actor, name string) (PKIProfileView, error)

ShowProfile returns a named profile with its policy and bindings and audits the read. Missing profiles return not found; authorization, storage, policy decoding, and audit errors are propagated.

func (*PKI) UnbindProfile

func (s *PKI) UnbindProfile(ctx context.Context, actor Actor, name, bindingID string) (PKIProfileView, error)

UnbindProfile removes one binding from the named profile and audits the change, returning the remaining bindings. A missing profile or binding returns not found; a lost deletion returns ErrPKIProfileRace. Authorization, storage, policy decoding, and audit errors are propagated.

func (*PKI) UpdateProfile

func (s *PKI) UpdateProfile(ctx context.Context, actor Actor, name string, policy pki.Policy, expectedRowVersion int64) (PKIProfileView, error)

UpdateProfile replaces a profile's policy, but only with a provable narrowing (ADR D5). expectedRowVersion, when non-zero, pins the version the operator reviewed, so a concurrent edit cannot be silently overwritten.

type PKIBoundProfileView

type PKIBoundProfileView struct {
	Name   string
	Policy pki.Policy
}

PKIBoundProfileView is what an environment principal may see of a profile bound to its environment: the policy it issues under, never the bindings.

type PKIIssuerRequest

type PKIIssuerRequest struct {
	// Mode is root, intermediate or import. Rotation ignores it and follows
	// the issuer's own kind and origin.
	Mode               string
	Name               string
	CommonName         string
	Organization       string
	KeyAlgorithm       string
	TTL                time.Duration
	ParentName         string
	CRLDistributionURL string
	// Import material, protected input only. PrivateKeyPEM is zeroed by the
	// caller after the call returns.
	PrivateKeyPEM  []byte
	CertificatePEM string
	ChainPEM       string
}

PKIIssuerRequest creates (or rotates to) an issuer version.

type PKIIssuerResult

type PKIIssuerResult struct {
	Issuer PKIIssuerView
}

PKIIssuerResult is a created version. CSRPEM is set for a pending intermediate, for the operator's offline root to sign.

type PKIIssuerView

type PKIIssuerView struct {
	ID                 string
	Name               string
	Version            int64
	Kind               string
	Origin             string
	ParentID           string
	State              string
	KeyAlgorithm       string
	KeyFingerprint     string
	CertificatePEM     string
	CSRPEM             string
	ChainPEM           string
	SubjectCN          string
	SubjectOrg         string
	NotBefore          *time.Time
	NotAfter           *time.Time
	CRLDistributionURL string
	RestoreHold        bool
	IssuedCount        int64
	CRLNumber          int64
	CRLThisUpdate      *time.Time
	CRLNextUpdate      *time.Time
	CreatedAt          time.Time
	UpdatedAt          time.Time
}

PKIIssuerView is an issuer version's public surface. It has no private-key field: the key is sealed, non-exportable, and never leaves the service.

type PKIProfileBindingView

type PKIProfileBindingView struct {
	ID            string
	OrgID         string
	ProjectID     string
	EnvironmentID string
	CreatedAt     time.Time
}

PKIProfileBindingView is one explicit reach of a profile.

type PKIProfileView

type PKIProfileView struct {
	ID         string
	Name       string
	Policy     pki.Policy
	Bindings   []PKIProfileBindingView
	RowVersion int64
	CreatedAt  time.Time
	UpdatedAt  time.Time
}

PKIProfileView is a profile with its policy and bindings.

type PairRemoteRequest

type PairRemoteRequest struct{ Name, RequesterState, InviteBundle string }

type PairingFinished

type PairingFinished struct {
	ServerMessage, Credential string
	Connection                ConnectionView
}

type PairingInviteCreated

type PairingInviteCreated struct {
	Invite       PairingInviteView
	InviteBundle string
}

type PairingInviteList

type PairingInviteList struct {
	Items              []PairingInviteView
	Origin             string
	ConfigurationError string
}

type PairingInviteView

type PairingInviteView struct {
	ID, Label, Origin, SPKIPin                                       string
	CreatedAt, ExpiresAt, CredentialExpiresAt, RevokedAt, ConsumedAt time.Time
}

type PairingPrepared

type PairingPrepared struct {
	Phrase, RequesterState string
	ExpiresAt              time.Time
}

type PairingStarted

type PairingStarted struct{ Exchange, ServerMessage string }

type PasskeyView

type PasskeyView struct {
	ID           string
	Label        string
	Discoverable bool
	Disabled     bool
	CreatedAt    time.Time
	LastUsedAt   time.Time
}

PasskeyView is the transport's view of an enrolled credential.

type PendingDraft

type PendingDraft struct {
	OwnerID            string
	Valid              bool
	ValidationDeferred bool `json:"validation_deferred"`
	VersionID          string
	KeyID              string
	Name               string
	Classification     string
	Operation          string
	StagedFromRevision int64
	CreatedAt          time.Time
	Revealed           bool
	Value              string
}

PendingDraft is one caller-owned draft in an environment. Value carries plaintext only for a revealed config set; secret and unset drafts never carry material on this surface.

type PinAction

type PinAction string
const (
	PinCreated    PinAction = "created"
	PinReassigned PinAction = "reassigned"
	PinRenewed    PinAction = "renewed"
)

type PinView

type PinView struct {
	ID                          string
	WorkloadPrincipalID         string
	Revision                    int64
	AuthorityPrincipalID        string
	ExpiresAt                   time.Time
	CreatedAt                   time.Time
	AuthorizedAt                time.Time
	HistoryAuthorized           bool
	SchemaOverride              bool
	Expired                     bool
	ReleaseRetentionConsequence RetentionConsequence
}

type Pins

type Pins struct {
	DB      *store.DB
	Keyring *crypto.Keyring
	Auth    *Auth
	Now     func() time.Time
}

func (*Pins) List

func (s *Pins) List(ctx context.Context, actor Actor, scope domain.Scope) ([]PinView, error)

func (*Pins) Release

func (s *Pins) Release(ctx context.Context, actor Actor, scope domain.Scope, workloadPrincipalID domain.PrincipalID) (ReleasePinResult, error)

func (*Pins) Set

func (s *Pins) Set(ctx context.Context, actor Actor, scope domain.Scope, request SetPinRequest) (SetPinResult, error)

type PlanDiff

type PlanDiff struct {
	Environments   definitions.KindDiff `json:"environments"`
	KeyGroups      definitions.KindDiff `json:"key_groups"`
	Keys           definitions.KindDiff `json:"keys"`
	KeyDeletions   []KeyDeletion        `json:"key_deletions"`
	EnvDeletions   []EnvDeletion        `json:"env_deletions"`
	RevealRequired []string             `json:"reveal_required"`
}

PlanDiff is the rendered plan preview: the structural diff plus the concrete deletion impact.

type PlanView

type PlanView struct {
	ID                    string
	Digest                string
	BaseRevision          *int64
	CurrentRevision       int64
	Additive              bool
	ExpiresAt             time.Time
	ProtectedEnvironments []string
	Diff                  PlanDiff
	DeletionsPresent      bool
	RevealRequired        []string
}

PlanView is the plan response — the impact preview a plan IS.

type PolicyChange

type PolicyChange struct {
	MaxFiniteLifetime  time.Duration
	AllowIndefinite    bool
	MaxLiveCredentials int64
	// Confirm acknowledges the enumerated affected credentials. The ADR
	// requires them shown to the actor BEFORE the change commits, so an
	// unconfirmed tightening answers with the list and refuses.
	Confirm bool
}

PolicyChange is a requested policy, plus the acknowledgement a TIGHTENING needs.

type PolicyResult

type PolicyResult struct {
	// Applied is false when the change was a PREVIEW: a tightening whose
	// affected credentials the actor has not yet acknowledged. The ADR
	// requires them enumerated BEFORE the change commits, so an unconfirmed
	// tightening answers with the list and changes nothing. It is a distinct
	// field rather than an error because the enumeration IS the answer, and
	// a refusal whose body cannot carry it would enumerate to nobody.
	Applied bool
	Policy  PolicyView
	// Affected is the enumeration: every live credential the change clamps
	// or strands. It is populated on the refusal too, which is the point.
	Affected []AffectedCredentialView
	Clamped  int64
}

PolicyResult reports what a policy change did, or — when it was a preview — what it would have done.

type PolicyView

type PolicyView struct {
	MaxFiniteLifetime  time.Duration
	AllowIndefinite    bool
	MaxLiveCredentials int64
	UpdatedAt          time.Time
	UpdatedBy          domain.PrincipalID
}

PolicyView is the instance lifetime governance as the API renders it.

type PreparePairingRequest

type PreparePairingRequest struct {
	Phrase    *string
	WordCount *int
}

type PrivacyExport

type PrivacyExport struct {
	Sessions    []authz.PrivacySession   `json:"sessions"`
	Version     int                      `json:"version"`
	ExportedAt  time.Time                `json:"exported_at"`
	Account     authz.PrivacyAccountView `json:"account"`
	Identities  []PrivacyIdentity        `json:"identities"`
	Grants      []domain.Grant           `json:"grants"`
	Activity    []authz.PrivacyActivity  `json:"activity"`
	Limitations []string                 `json:"limitations"`
}

PrivacyExport is a reviewed subject-access starting point, not an assertion that arbitrary secret payloads and third-party records have been inspected.

type PrivacyIdentity

type PrivacyIdentity struct {
	Kind      string    `json:"kind"`
	Issuer    string    `json:"issuer"`
	Subject   string    `json:"subject"`
	CreatedAt time.Time `json:"created_at"`
}

type PrivacyReceipt

type PrivacyReceipt struct {
	InstanceID  string    `json:"instance_id"`
	Version     int       `json:"version"`
	PrincipalID string    `json:"principal_id"`
	AccountID   string    `json:"account_id"`
	Action      string    `json:"action"`
	AppliedAt   time.Time `json:"applied_at"`
}

PrivacyReceipt belongs outside the database backup retention boundary. Reapply each approved receipt to a restored database before restoring principal access.

type ProfileUpdate

type ProfileUpdate struct {
	Username    string
	DisplayName string
}

ProfileUpdate is everything the profile surface may change. It carries no email by construction.

type Project

type Project struct {
	CanManagePolicy *bool
	CanDelete       *bool
	ID              string
	OrgID           string
	Name            string
	CreatedAt       time.Time
}

Project is the service layer's project.

type ProjectCapacity

type ProjectCapacity struct {
	KeyLimitOverride *int
	InstanceDefault  int
	InstanceMaximum  int
	EffectiveLimit   int
	KeyCount         int64
	EnvironmentCount int64
	Revision         int64
	Inherited        bool
	Capped           bool
}

ProjectCapacity resolves the saved project policy against the current owner configuration. A saved override survives a lower instance maximum.

type ProjectRetention

type ProjectRetention struct {
	Inherited bool
	Policy    RetentionPolicy
}

ProjectRetention is the effective project policy and whether it is inherited from the organization rather than stored on the project.

type ProjectSettings

type ProjectSettings struct {
	DefaultKeysPerProject int
	MaxKeysPerProject     int
	DB                    *store.DB
	Auth                  *Auth
	Now                   func() time.Time
}

ProjectSettings owns the `project-settings` surface. It holds the Auth service because lowering an environment's effective window is not a column write: it invalidates the open windows, enumerates the principals the transition strands and audits the transition — the library #54 shipped for exactly this caller.

func (*ProjectSettings) GetCapacity

func (s *ProjectSettings) GetCapacity(ctx context.Context, actor Actor, scope domain.Scope) (ProjectCapacity, error)

GetCapacity reads metadata and usage under project-settings authority.

func (*ProjectSettings) GetEnvironment

func (s *ProjectSettings) GetEnvironment(ctx context.Context, actor Actor, scope domain.Scope) (EnvironmentSettings, error)

GetEnvironment reads one environment's protection state and window. It is bare `read(E)`: an environment's protection state is part of its public shape, and hiding it from a reader would make the reveal ceremony inexplicable to the person subject to it.

func (*ProjectSettings) GetMachineReveal

func (s *ProjectSettings) GetMachineReveal(ctx context.Context, actor Actor, scope domain.Scope) (MachineRevealSettings, error)

GetMachineReveal reads the project's machine-reveal opt-in under `read@project`.

func (*ProjectSettings) SetCapacity

func (s *ProjectSettings) SetCapacity(ctx context.Context, actor Actor, scope domain.Scope, want CapacityUpdate) (ProjectCapacity, error)

SetCapacity serializes with key admission, rejects stale editors, and audits actual policy changes. Lowering capacity preserves all existing keys.

func (*ProjectSettings) SetEnvironment

func (s *ProjectSettings) SetEnvironment(ctx context.Context, actor Actor, scope domain.Scope, want EnvironmentSettings) (EnvironmentSettings, error)

SetEnvironment writes both knobs as one fact, because they are one: marking an environment protected caps its window, so a surface that could write them apart would have an observable state where the flag is set and the window is not yet capped.

func (*ProjectSettings) SetMachineReveal

func (s *ProjectSettings) SetMachineReveal(ctx context.Context, actor Actor, scope domain.Scope, enabled bool) (MachineRevealSettings, error)

SetMachineReveal flips the project's machine-reveal opt-in (source-of-truth ADR: "Granting `reveal` to a machine identity is an explicit, documented, per-project operator opt-in, never a default"). The formula carries `project-settings` and `reveal` at project depth and is MFA-mandatory through the latter. Both directions are audited; the flip itself touches no grant row - withdrawal makes every machine `reveal` inert on the next fetch because the chokepoint and the delivery path read the column live.

type Projects

type Projects struct {
	DB *store.DB
}

Projects owns the project surface.

func (*Projects) Create

func (s *Projects) Create(ctx context.Context, actor Actor, org domain.OrgID, name string) (Project, error)

Create makes a project inside org. The service addresses the scope; the chain the store writes comes from the proof authorize() minted after resolving that scope — never from these arguments.

Project names are NOT secret-scanned (#74, ADR §2 Surface 2): a project name is not definitions-bundle content, on the same ground org names are not (see Orgs.Create). Key/folder/environment/group fields are the scanned surface.

func (*Projects) Delete

func (s *Projects) Delete(ctx context.Context, actor Actor, scope domain.Scope) error

Delete removes a project. Like every delete on this surface it refuses rather than cascading: a project holding environments or folders is refused by the ancestry constraints as a conflict.

func (*Projects) Get

func (s *Projects) Get(ctx context.Context, actor Actor, scope domain.Scope) (Project, error)

func (*Projects) List

func (s *Projects) List(ctx context.Context, actor Actor, org domain.OrgID) ([]Project, error)

func (*Projects) Rename

func (s *Projects) Rename(ctx context.Context, actor Actor, scope domain.Scope, name string) (Project, error)

type ProviderInput

type ProviderInput struct {
	DisplayName     string
	Issuer          string
	ClientID        string
	ClientSecret    string
	Scopes          string
	AssurancePolicy *string
	Enabled         bool
	// CreateOnly distinguishes an API create from legacy internal upsert calls.
	// ExpectedRowVersion pins an API reconfiguration to the displayed row.
	CreateOnly         bool
	ExpectedRowVersion *int64
}

ProviderInput is a create-or-update request body.

type ProviderView

type ProviderView struct {
	Slug            string
	DisplayName     string
	Issuer          string
	ClientID        string
	Scopes          string
	RedirectURI     string
	AssurancePolicy *string
	Enabled         bool
	RowVersion      int64
}

ProviderView is a provider as returned to an administrator. The client secret never leaves the server, so it is absent here.

type Providers

type Providers struct {
	DB      *store.DB
	Keyring *crypto.Keyring
	// ExternalOrigin is the instance's public origin, used to build the
	// per-provider redirect URI (A1). Never derived from a request header.
	ExternalOrigin   string
	FederationPolicy federationhttp.Policy
	Now              func() time.Time
	Log              *slog.Logger
}

Providers is the OIDC provider administration service. Configuration is an instance-config operation authorized at the chokepoint; a security-material change (issuer is immutable, so client, secret, assurance policy, or disable) sweeps every session authenticated through the provider in the same tx (A4).

func (*Providers) Delete

func (s *Providers) Delete(ctx context.Context, actor Actor, slug string) error

Delete removes a provider and sweeps its federated sessions (A4). Its transaction rows and federated sessions cascade on the FK (A14); the sweep runs after the provider row is locked so the count is accurate and no mint can race the delete.

func (*Providers) Get

func (s *Providers) Get(ctx context.Context, actor Actor, slug string) (ProviderView, error)

Get returns one provider by slug.

func (*Providers) List

func (s *Providers) List(ctx context.Context, actor Actor) ([]ProviderView, error)

List returns every configured provider.

func (*Providers) Put

func (s *Providers) Put(ctx context.Context, actor Actor, slug string, in ProviderInput) (ProviderView, error)

Put creates a provider or reconfigures an existing one. The issuer is immutable on update (A3): a changed issuer is refused by name. Discovery is re-run at write time and the document's issuer must byte-equal the configured one. A reconfigure that changes security material sweeps federated sessions. Changing the client ID is refused with ErrPairwiseClientID when discovery advertises only pairwise subjects and identities remain linked under the issuer. Discovery failures return ErrProviderDiscovery, with the discovered issuer named when it differs. Authorization, storage and sealing errors propagate.

type PruneHealth

type PruneHealth struct {
	Diagnostics DiagnosticHealth
	LastSuccess time.Time
	Recorded    bool
	Stale       bool
	// PeakProjectBytes is the largest per-project stored payload across the
	// whole instance — value cells plus published snapshot entries (#185).
	// StorageWarn is true once it reaches ProjectStorageWarnBytes, the doctor /
	// metric / UI-banner warn for the per-project storage high-water.
	PeakProjectBytes int64
	StorageWarn      bool
	// Backup is the disaster-recovery half of the same operator read (#145):
	// latest export, RPO verdict, latest failure, latest restore drill.
	Backup BackupHealth
	// Adapters are the instance-wide deployment-adapter health counts (#157):
	// the label-free gauges and the doctor finding read the same numbers.
	Adapters store.AdapterHealthCounts
	// PKI is the private-PKI half (#154): certificates in the uncertain
	// `unknown` state and issuers held after a restore. PKIKnown is false when
	// the counts could not be read, which must never read as healthy.
	PKI      store.PKIGauges
	PKIKnown bool
}

PruneHealth is the persisted payload-pruner health state.

type PrunePolicy

type PrunePolicy struct {
	// RetainCount archives are kept within the hard 180-day ceiling, newest first.
	RetainCount int
	// RetainDays is the age past which an archive outside the retained set
	// is deleted. No count exemption extends the hard 180-day ceiling.
	RetainDays int
}

PrunePolicy is the retention pruner's two bounds.

type PruneResult

type PruneResult struct {
	Deleted []string
	Kept    int
	Expired int
}

PruneResult reports what one run did.

type PublishConformanceProbe

type PublishConformanceProbe interface {
	BeforeProjectLock(versionIDs []string)
	AfterBaselineRead(versionIDs []string)
}

PublishConformanceProbe exposes only the two checkpoints needed to prove publish serialization against both real engines.

type PublishRequest

type PublishRequest struct {
	VersionIDs                     []string
	PreviewToken                   string
	ConfirmedProtectedEnvironments []string
	// Secret-change approvals (#151). When a policy covers the addressed
	// environment, a bare publish is refused: the caller either creates a
	// request (both fields empty), merges an approved one (ApprovalRequestID
	// set), or emergency-bypasses one (ApprovalRequestID + Bypass set). Ignored
	// where no policy covers the environment. Purpose is the requester's
	// free-text reason, recorded on the created request.
	ApprovalRequestID string
	Bypass            *ApprovalBypass
	Purpose           string
}

PublishRequest carries the reviewed selection and the protected-environment decision. PreviewToken is required when any selected draft came from restore.

type PublishResult

type PublishResult struct {
	// Published names every version id that committed, INCLUDING the ones
	// key-group closure pulled in; ClosedIn names just the latter, so a caller
	// can tell what it asked for from what the coupling required.
	Published    []string
	ClosedIn     []string
	Environments []PublishedEnvironment
	// CreatedApprovalRequest is set, and every other field empty, when the
	// publish addressed a policy-covered environment with no approval presented:
	// a request was staged instead of a revision published (#151). The transport
	// answers 202 with the request rather than a publish result.
	CreatedApprovalRequest *ApprovalRequestSummary
}

PublishResult is one publish.

type PublishedEnvironment

type PublishedEnvironment struct {
	EnvironmentID string
	Revision      int64
	// ChangeToken is derived from the CURRENT root token key over this
	// snapshot's delivery manifest, never stored -- see the migration.
	ChangeToken string
	// SchemaRevision is the pinned input this snapshot was validated at.
	SchemaRevision int64
	ChangedKeys    []ChangedKey
}

PublishedEnvironment is one environment a materialization advanced.

type ReauthEvidence

type ReauthEvidence struct {
	Principal domain.PrincipalID
	// contains filtered or unexported fields
}

type ReauthIntent

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

ReauthIntent is the closed representation of one reauthentication decision. Its fields are private so purpose, operation, environment and key bindings cannot be assembled independently after the transport boundary has parsed them. Constructors below are the only way to create a value.

func NewAccessBypassReauthIntent

func NewAccessBypassReauthIntent(environmentID string) (ReauthIntent, error)

NewAccessBypassReauthIntent binds an emergency temporary-access decision to the environment (#152). Its unit is the environment alone: the decision is about standing authority there, not about any key's material. An empty environmentID returns an error wrapping domain.ErrInvalid.

func NewAdapterReauthIntent

func NewAdapterReauthIntent(operation string, environmentIDs []string) (ReauthIntent, error)

NewAdapterReauthIntent parses the wire adapter operation into one of four closed variants. Other authz operations cannot inhabit an adapter intent.

func NewApproveReauthIntent

func NewApproveReauthIntent(environmentID string, keyIDs []string) (ReauthIntent, error)

NewApproveReauthIntent binds an approver's vote to the request's environment and exact key set (#151).

func NewBypassReauthIntent

func NewBypassReauthIntent(environmentID string, keyIDs []string) (ReauthIntent, error)

NewBypassReauthIntent binds an emergency bypass to the request's environment and exact key set (#151).

func NewDeveloperCredentialReauthIntent

func NewDeveloperCredentialReauthIntent(environmentID string, keyIDs []string, ttl time.Duration, consent bool) (ReauthIntent, error)

func NewDisclosureReauthIntent

func NewDisclosureReauthIntent(purpose ReauthPurpose, environmentIDs, keyIDs []string) (ReauthIntent, error)

NewDisclosureReauthIntent parses the wire purpose at the transport boundary. Past this constructor purpose, operation, environment and keys travel as one value and cannot be recombined.

func NewMintReauthIntent

func NewMintReauthIntent(environmentID string, keyIDs []string) (ReauthIntent, error)

func NewPublishReauthIntent

func NewPublishReauthIntent(environmentID string, keyIDs []string) (ReauthIntent, error)

func NewRejectReauthIntent

func NewRejectReauthIntent(environmentID string, keyIDs []string) (ReauthIntent, error)

NewRejectReauthIntent binds an approver's rejection to the request's environment and exact key set (#151).

func NewRevealReauthIntent

func NewRevealReauthIntent(environmentID string, keyIDs []string) (ReauthIntent, error)

func NewSelfConfigReauthIntent

func NewSelfConfigReauthIntent(target SelfConfigReauthTarget) (ReauthIntent, error)

func NewUnboundReauthIntent

func NewUnboundReauthIntent(environmentID string) (ReauthIntent, error)

func (ReauthIntent) EnvironmentIDs

func (i ReauthIntent) EnvironmentIDs() []string

func (ReauthIntent) ForEnvironment

func (i ReauthIntent) ForEnvironment(environmentID string) (ReauthIntent, error)

ForEnvironment selects one environment from an already canonical intent. It is used where one member of an adapter or CLI environment set is about to be signed or consumed; a non-member cannot be represented by the result.

func (ReauthIntent) KeyIDs

func (i ReauthIntent) KeyIDs() []string

func (ReauthIntent) Operation

func (i ReauthIntent) Operation() (authz.Operation, error)

func (ReauthIntent) Purpose

func (i ReauthIntent) Purpose() (ReauthPurpose, error)

type ReauthPurpose

type ReauthPurpose string

ReauthPurpose is the closed set of decisions a disclosure ceremony can authorize (#58, review R1 finding 3).

It is part of the SIGNED binding, not decoration on a modal. A ceremony is "purpose-bound" only if the purpose is inside the thing the authenticator signed and the thing consumption matches: otherwise an assertion the human gave to "reveal · production" is spendable on "publish into · production" over the same keys, which is a different decision they were never shown.

The closed members distinguish reading plaintext, taking it out of an environment, putting it into one, minting or widening a machine path, and the approval decisions below.

const (
	// PurposeReveal renders plaintext to the principal — cell, bulk or diff.
	PurposeReveal ReauthPurpose = "reveal"
	// PurposeCopy takes stored material OUT of an environment: the source half
	// of a copy or clone, including copy-without-display.
	PurposeCopy ReauthPurpose = "copy"
	// PurposePublish delivers material INTO a protected environment.
	PurposePublish ReauthPurpose = "publish"
	// PurposeMint is the credential mint/widen conjunct (#61): disclosure by
	// proxy toward a credential the actor controls. It is its own member for
	// the same reason the others are — a ceremony given to "mint a token for
	// production" must not be spendable on reading production.
	PurposeMint ReauthPurpose = "mint"
	// PurposeAdapter is the signed adapter-routing decision. It cannot reuse
	// PurposeMint: consent to mint a machine credential is not consent to
	// adopt and overwrite a provider-side name.
	PurposeAdapter ReauthPurpose = "adapter"
	// PurposeApprove is an approver's vote on a change-approval request (#151):
	// the authenticator signs "I approve this exact change set in this
	// environment", bound to the request's key set. It cannot reuse any
	// disclosure purpose — an assertion given to reveal production is not
	// consent to approve a change to it.
	PurposeApprove ReauthPurpose = "approve"
	// PurposeReject is an approver's rejection. It is distinct from approve so
	// the signed decision always matches the button the human selected.
	PurposeReject ReauthPurpose = "reject"
	// PurposeBypass is the emergency-bypass decision (#151): a named bypasser
	// signs "I am committing this change WITHOUT the required approval", the
	// single most consequential action the engine allows, so it is its own
	// purpose and additionally carries a reason.
	PurposeBypass ReauthPurpose = "bypass"
	// PurposeAccess is emergency temporary access (#152): a named bypasser
	// signs "I am taking these capabilities in this environment WITHOUT the
	// required approval". It is distinct from PurposeBypass: consent to force a
	// reviewed change through is not consent to take standing authority.
	PurposeAccess ReauthPurpose = "access"
)
const PurposeDeveloperCredential ReauthPurpose = "developer-credential"
const PurposeSelfConfig ReauthPurpose = "self-config"

func (ReauthPurpose) Valid

func (p ReauthPurpose) Valid() bool

Valid reports membership of the closed set. An unknown purpose is refused rather than defaulted: a binding nobody can name is a binding nobody checks.

type ReauthResult

type ReauthResult struct {
	SessionToken string
	// CSRFToken is the rotated synchronizer token that travels with a rotated
	// browser session. Without it the caller's next state-changing request
	// would present a stale token against a freshly minted verifier and be
	// refused (#56).
	CSRFToken      string
	SessionID      string
	EnvironmentID  string
	SingleDecision bool
	WindowExpires  time.Time
}

ReauthResult reports a reauthentication that opened (or single-decision-armed) a window, plus the rotated session token.

type ReconcileResult

type ReconcileResult struct {
	Accepted   int
	Duplicates int
}

ReconcileResult reports the idempotent outcome of one bounded batch.

type Recovery

type Recovery struct{ DB *store.RecoveryDB }

Recovery is the bounded operator drill surface. Its database cannot be used by ordinary services and every operation retains the active scratch guard.

func (*Recovery) AutoCredentialProof

func (s *Recovery) AutoCredentialProof(ctx context.Context, kr *crypto.Keyring) error

AutoCredentialProof selects one existing principal in the restored scratch database, reconciles it and exercises the normal credential lifecycle. No method on the live Restore surface performs automatic reconciliation.

func (*Recovery) MintAndRevoke

func (s *Recovery) MintAndRevoke(ctx context.Context, kr *crypto.Keyring, principal domain.PrincipalID, scope domain.Scope) error

MintAndRevoke exercises the same authorization, policy, aggregate writes and audit events as the runtime identity surface. No credential is returned.

func (*Recovery) ProveValuesReadable

func (s *Recovery) ProveValuesReadable(ctx context.Context, kr *crypto.Keyring) (bool, error)

func (*Recovery) Reconcile

func (s *Recovery) Reconcile(ctx context.Context, principal domain.PrincipalID) (Status, error)

func (*Recovery) Status

func (s *Recovery) Status(ctx context.Context) (Status, error)

type RecoveryResult

type RecoveryResult struct {
	Authority string
	ExpiresAt time.Time
}

RecoveryResult is a session-less credential-establishment authority minted by consuming a recovery code. It creates NO session, NO assurance and NO window: the holder establishes a new password with it and then logs in like anyone.

type Reencrypt

type Reencrypt struct {
	DB      *store.DB
	Keyring *crypto.Keyring
	// Budget applies the §179 fail-closed default (60/min·principal, 8/org) to
	// the reencrypt trigger — a row-proportional crypto walk with no named
	// category. Nil disables it.
	Budget *Budget
	Now    func() time.Time
	// ChunkSize / ChunkPause override the #187 defaults; zero uses them. Tests
	// set a tiny chunk and no pause.
	ChunkSize  int
	ChunkPause time.Duration
	// BeforeRetire, when set, runs after the walk and before the retire's dryness
	// gate. Test-only (nil in production): it lets a test interleave a rotate-dek
	// or seed a straggler into the window the gate must refuse.
	BeforeRetire func(context.Context) error
	// AfterChunk, when set, runs inside each chunk transaction after its rows are
	// processed and before commit, receiving the table being walked. Test-only
	// (nil in production): returning a retryable error (store.ErrRetrySerialization)
	// exercises the tx.Write replay path, proving a chunk's cursor and moved-count
	// outputs are attempt-local and never published on a rolled-back attempt.
	AfterChunk func(ctx context.Context, table string) error
}

Reencrypt walks a scope's retained ciphertext onto the active DEK version and (once every table in the scope is on it) retires the superseded versions — the completion half of a DEK rotation (encryption-model ADR § Rotation, #75; ops-spec §9 bounds, #187).

The walk is chunked (default 100 rows) with a fixed inter-chunk pause (default 100 ms) so a large scope does not monopolize a connection, and it is resumable by construction: a row already on the active version is skipped, so a re-run (or a crash mid-walk) continues from where it left off. Each row is moved under a compare-and-swap on its old ciphertext — a concurrent write that replaced the row leaves it on a fresh version and the CAS matches nothing, so reencrypt never resurrects a superseded value.

func (*Reencrypt) ReencryptInstance

func (s *Reencrypt) ReencryptInstance(ctx context.Context, actor Actor) (ReencryptResult, error)

ReencryptInstance walks the instance-DEK ciphertext tables onto the active instance DEK version, then retires the superseded versions. Instance-scoped: no tenant chain, one InstanceSealer for the whole walk.

func (*Reencrypt) ReencryptProject

func (s *Reencrypt) ReencryptProject(ctx context.Context, actor Actor, orgID, projectID string) (ReencryptResult, error)

ReencryptProject moves a project's retained ciphertext, including software transit key material, onto the active DEK version and returns the moved row count. Superseded DEK versions are retired only after all covered tables are on the active version. Keyring, authorization, budget, and store errors propagate; earlier committed chunks remain moved if a later step fails.

func (*Reencrypt) SweepRetiring

func (s *Reencrypt) SweepRetiring(ctx context.Context) ([]RetiringScope, error)

SweepRetiring reports every scope whose DEK still has a retiring version. It is read-only and takes no operator proof: it runs the same boot-surface AllOpenableTier3 read the keyring loads from (SiteBoot authority, no writes) and groups the openable versions by scope. The scheduler logs a warning per result so an operator runs `reencrypt` — reencrypt stays an operator act, and the sweep grants the scheduler no write access to any ciphertext table (#75/#187, scheduler option A).

type ReencryptResult

type ReencryptResult struct {
	Scope     string
	OrgID     string
	ProjectID string
	RowsMoved int
}

ReencryptResult reports one reencrypt run: the scope and how many rows moved.

type RefusalHealth

type RefusalHealth struct {
	Healthy           bool
	Failures          uint64
	PendingSince      int64
	InFlight, Waiting int
}

type RefusalSignals

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

RefusalSignals owns bounded work and health, never authentication or quotas. Staging and sealing are coordinated by one locked datastore row across nodes.

func NewRefusalSignals

func NewRefusalSignals(db *store.DB) *RefusalSignals

NewRefusalSignals creates a bounded accounting owner for the application runtime.

func (*RefusalSignals) Record

func (s *RefusalSignals) Record(ctx context.Context, sample audit.RefusalSample) error

Record durably stages one request sample or exposes accounting failure.

func (*RefusalSignals) RefusalHealth

func (s *RefusalSignals) RefusalHealth() RefusalHealth

RefusalHealth exposes the last accounting result and current bounded work.

func (*RefusalSignals) Run

func (s *RefusalSignals) Run(ctx context.Context)

Run flushes quiet windows and recovers pending staging on startup. Every attempt is synchronous and deadline-bound; cancellation joins this worker. Each tick exercises the locked writer path even when staging is empty. A read-only pre-check would change that health probe and add another datastore protocol; the approved minimum keeps one bounded attempt per second.

func (*RefusalSignals) Seal

func (s *RefusalSignals) Seal(ctx context.Context) error

Seal checks and atomically publishes expired staging under the writer owner.

type Registration

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

Registration is the registration policy (#606, #579 as amended; spec sections 2.1, 3, 4 and 5): at most one policy per org and one at instance scope, administered by that scope's manage-members holder under fresh proof, and the only path by which an unsolicited unknown identity becomes an account. The sign-up legs that USE a policy are #607 (federated) and #608 (local); this file owns the policy itself, its standing delegation, its preconditions and the public door `/auth/methods` renders.

Build it with NewRegistration: every dependency is required, so a missing mail predicate is a construction error rather than a silent "unconfigured".

func NewRegistration

func NewRegistration(c RegistrationConfig) (*Registration, error)

NewRegistration validates the configuration.

func (*Registration) Delete

func (s *Registration) Delete(ctx context.Context, actor Actor, scope RegistrationScope, proof string) error

Delete closes the scope's registration: the policy row goes, and so do the pending local sign-ups it admitted, inside the same transaction, each with `registration.signup_expired {cause: policy-deleted}` (spec section 4). Reauth-gated like Put; no session is purged.

func (*Registration) Get

Get returns the scope's policy, or nil when the scope has none: closed. The read is recorded as a membership-surface read.

func (*Registration) Put

Put replaces the scope's policy (creating it when absent) and makes the caller its authority principal (#579 d4: any edit reassigns authority). Reauth-gated: proof is verified before the transaction and consumed in it; the caller's sessions are untouched. Every precondition is evaluated inside the write transaction.

func (*Registration) SignupDoor

func (s *Registration) SignupDoor(ctx context.Context, scope RegistrationScope) (SignupDoor, error)

SignupDoor renders one scope's public sign-up door. Proof-free public discovery like the rest of `/auth/methods`: an unknown org and an org without a policy are the same closed door, byte for byte.

type RegistrationConfig

type RegistrationConfig struct {
	DB                   *store.DB
	Auth                 *Auth
	Now                  func() time.Time
	PublicOriginExplicit bool
	MailConfigured       func(context.Context) (bool, error)
}

RegistrationConfig carries Registration's dependencies. Auth may be nil only where no network caller exists (local host authority); a network mutation without it fails closed.

type RegistrationExternalEntry

type RegistrationExternalEntry struct {
	Provider domain.ProviderRef
	Claim    string
	Values   []string
	// DisplayName is the provider's, on a view only.
	DisplayName string
}

RegistrationExternalEntry admits one federated provider, optionally behind an allowlist of one issuer-specific string claim.

type RegistrationLanding

type RegistrationLanding struct {
	Kind     LandingKind
	Template domain.Template // org-template only
	Cap      int64           // fresh-org only
}

RegistrationLanding is where a sign-up arrives.

type RegistrationLocalEntry

type RegistrationLocalEntry struct {
	Domains []string
}

RegistrationLocalEntry admits email + password sign-up (#584), optionally only for addresses under the listed domains.

type RegistrationPolicyInput

type RegistrationPolicyInput struct {
	External []RegistrationExternalEntry
	Local    *RegistrationLocalEntry
	Landing  RegistrationLanding
}

RegistrationPolicyInput is a full replacement (PUT). The caller becomes the authority principal.

type RegistrationPolicyView

type RegistrationPolicyView struct {
	ID                   string
	Org                  domain.OrgID // "" = instance scope
	External             []RegistrationExternalEntry
	Local                *RegistrationLocalEntry
	Landing              RegistrationLanding
	AuthorityPrincipalID domain.PrincipalID
	Active               bool
	InactiveCause        InactiveCause
	// InactivePrecondition names the failing precondition when InactiveCause
	// is `precondition`, with the provider when one is involved.
	InactivePrecondition string
	// FreshOrgCount is set for a fresh-org landing: the `n` of `n / cap`.
	FreshOrgCount *int64
	RowVersion    int64
	CreatedAt     time.Time
	UpdatedAt     time.Time
}

RegistrationPolicyView is a policy as the Members panel renders it, with the standing delegation and preconditions evaluated at read time.

type RegistrationPrecondition

type RegistrationPrecondition string

RegistrationPrecondition names a precondition (api-cli-spellings section 8). At write it refuses 400 naming itself (and the provider row where relevant); at use it is the named reason behind `precondition`.

const (
	PreconditionNoPublicOrigin           RegistrationPrecondition = "no-public-origin"
	PreconditionMailerUnconfigured       RegistrationPrecondition = "mailer-unconfigured"
	PreconditionProviderDisabled         RegistrationPrecondition = "provider-disabled"
	PreconditionProviderMissingEmail     RegistrationPrecondition = "provider-missing-email-scope"
	PreconditionCapZero                  RegistrationPrecondition = "cap-zero"
	PreconditionTemplateNotOrgApplicable RegistrationPrecondition = "template-not-org-applicable"
	// PreconditionProviderMissing is a stored entry whose provider row was
	// deleted: nothing auto-deletes entries (#579 d6).
	PreconditionProviderMissing RegistrationPrecondition = "provider-missing"
	// PreconditionProviderKindUnsupported is a provider kind with no
	// configured table for this build.
	PreconditionProviderKindUnsupported RegistrationPrecondition = "provider-kind-unsupported"
)

type RegistrationScope

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

RegistrationScope addresses one policy: the instance, or one org. The zero value addresses nothing and is refused, so "no org" can never silently mean "the instance".

func InstanceRegistrationScope

func InstanceRegistrationScope() RegistrationScope

InstanceRegistrationScope addresses the instance policy.

func OrgRegistrationScope

func OrgRegistrationScope(org domain.OrgID) RegistrationScope

OrgRegistrationScope addresses one org's policy.

func (RegistrationScope) Instance

func (s RegistrationScope) Instance() bool

Instance reports whether the scope is the instance.

func (RegistrationScope) Org

func (s RegistrationScope) Org() domain.OrgID

Org is the addressed org, "" for the instance.

type ReleasePinResult

type ReleasePinResult struct {
	Revision             int64
	RetentionConsequence RetentionConsequence
}

ReleasePinResult describes transaction-time retention truth. A concurrent GC that commits first yields already_collected; one that runs after release may immediately collect a collection_eligible payload.

type RemoteOrg

type RemoteOrg struct {
	Name     string
	Projects []string
}

RemoteOrg is one organisation's name and its projects', as served.

type RemotePairings

type RemotePairings struct {
	DB      *store.DB
	Keyring *crypto.Keyring
	Remotes *Remotes
	Now     func() time.Time
	// Serving identity is captured from the active application generation,
	// never from invitation input or request headers. Resolution may perform a
	// bounded TLS handshake, so CreateInvite authorizes before invoking it.
	Origin             string
	ConfigurationError string
	ResolveSPKIPin     func(context.Context) (string, error)
}

RemotePairings owns only directory pairing. It never consents to workspace origins and never issues a human workspace session.

func (*RemotePairings) CreateInvite

func (*RemotePairings) Finish

func (s *RemotePairings) Finish(ctx context.Context, exchange, message, proof string) (PairingFinished, error)

Finish consumes its exchange even for an invalid PAKE proof. Returning an authentication failure from inside the transaction would roll that update back and allow unlimited guesses against the same admitted attempt.

func (*RemotePairings) ListInvites

func (s *RemotePairings) ListInvites(ctx context.Context, actor Actor) (PairingInviteList, error)

func (*RemotePairings) Pair

func (*RemotePairings) Prepare

func (*RemotePairings) RevokeInvite

func (s *RemotePairings) RevokeInvite(ctx context.Context, actor Actor, id string) error

func (*RemotePairings) Start

func (s *RemotePairings) Start(ctx context.Context, capability, publicJWK string) (PairingStarted, error)

type RemoteView

type RemoteView struct {
	ID        string
	Name      string
	URL       string
	SPKIPin   string
	CreatedAt time.Time
	CreatedBy domain.PrincipalID

	// State is the operator-visible outcome of the most recent fetch, from
	// remotefetch's closed enum. Empty only for an entry that has somehow
	// never been fetched, which `remote add` makes unreachable.
	State string
	// LastAttemptAt is when the most recent fetch ran, successful or not.
	LastAttemptAt time.Time
	// ObservedAt is when the listing below was actually observed. Zero means
	// there has never been a successful fetch.
	ObservedAt time.Time
	// Stale reports that the listing is a SNAPSHOT rather than current — the
	// card's "unreachable 2h, last known state shown". It is computed from the
	// outcome, not from the age: a fetch that just failed makes even a
	// one-second-old snapshot stale.
	Stale bool
	// StaleFor is the snapshot's age at read time, the number the card prints
	// beside "unreachable". Zero when not stale.
	StaleFor time.Duration

	Identity     string
	Version      string
	OrgCount     int64
	ProjectCount int64
	Orgs         []RemoteOrg
}

RemoteView is one directory card entry: the stored configuration plus the last-known state. Never the credential — there is no field for it.

type Remotes

type Remotes struct {
	DB      *store.DB
	Keyring *crypto.Keyring
	// Fetch is the outbound client. A nil Fetch is a hard error at the first
	// fetch rather than a silent skip: a directory that quietly stopped
	// fetching would show stale data as current, which is the one thing the
	// freshness model exists to prevent.
	Fetch *remotefetch.Client
	Now   func() time.Time
	// contains filtered or unexported fields
}

Remotes is the viewing side's service.

func (*Remotes) AddRemote

func (s *Remotes) AddRemote(ctx context.Context, actor Actor, name, rawURL, pin, credential string) (RemoteView, error)

AddRemote runs the connection ceremony's server half and commits the entry only if it verifies.

ORDER IS LOAD-BEARING and it is the ADR's. The steps before this one are the caller's because they are interactive: the CLI displays the SPKI fingerprint, takes the human's confirmation, and then reads the remote's pre-auth meta endpoint over that pinned connection to check protocol revision — all before it asks for the credential (`internal/cli/remotes.go`, addRemote).

The web add form does NOT perform a meta read, and does not need one: it posts an already-pasted credential, and what decides whether the entry exists is the authenticated fetch below — a peer too old to serve the directory fails it. The CLI's meta read buys the ORDER (refuse before a secret is typed), not a check this method depends on.

What happens HERE is the authenticated directory fetch — which returns the remote's instance identity, at which point self-connection and duplicate-identity refusal fire — BEFORE the row is written.

The fetch therefore runs OUTSIDE the write transaction, deliberately: a ten-second network deadline inside a write transaction would hold sqlite's single writer for ten seconds per add. The identity checks that depend on stored state are re-done inside the transaction, so the window between the two cannot produce a self-connected or duplicated entry.

func (*Remotes) ListRemotes

func (s *Remotes) ListRemotes(ctx context.Context, actor Actor) ([]RemoteView, error)

ListRemotes is the directory card: every entry, fetched on view.

ON-VIEW FETCH, no poller. The fetch happens because a holder of `instance-directory` is looking, and at no other moment — which is also what bounds the credential's use to human-initiated moments.

The fetch runs BETWEEN two transactions for the reason AddRemote's does: a fan-out of ten-second deadlines must not hold a write transaction. The read transaction takes the entries and their sealed credentials; the write transaction records the outcomes and the audit event.

func (*Remotes) RemoteOrigins

func (s *Remotes) RemoteOrigins(ctx context.Context, actor Actor) ([]string, error)

RemoteOrigins is the viewing side's own CSP input: the origins of every configured remote, for the dynamic `connect-src` extension. A closed list read from the entries themselves, never a wildcard.

Its document caller must authenticate and hold instance-directory access. This metadata-only read never originates a remote connection.

func (*Remotes) RemoveRemote

func (s *Remotes) RemoveRemote(ctx context.Context, actor Actor, name string) error

RemoveRemote destroys the entry, its credential and its snapshot.

It does NOT revoke anything on the serving side, and the surfaces say so every time: destroying the local copy is not revocation, and pretending otherwise would leave a live credential the operator believes is dead.

func (*Remotes) RenameRemote

func (s *Remotes) RenameRemote(ctx context.Context, actor Actor, name, newName string) (RemoteView, error)

RenameRemote changes the display name — the ADR's one mutable field. There is no URL or pin edit anywhere, by construction: re-pointing a stored credential at a different host is the credential-redirect attack, so re-pointing is remove + add, which re-runs the full human ceremony.

func (*Remotes) ShowRemote

func (s *Remotes) ShowRemote(ctx context.Context, actor Actor, name string) (RemoteView, error)

ShowRemote is one entry, same ceremony.

type ReplaceRulesSpec

type ReplaceRulesSpec struct {
	Org    domain.OrgID
	Target domain.PrincipalID
	Revoke []string
	Create []RuleSpec
}

ReplaceRulesSpec is one atomic change to a person's access card. Rule IDs are immutable, so a missing ID refuses a stale edit rather than reapplying it.

type ResetResult

type ResetResult struct {
	Authority     string
	AuthorityID   string
	TargetAccount string
	TargetUser    string
	ExpiresAt     time.Time
}

ResetResult carries the one-time authority out to the caller, delivered once through the print triad and never re-displayed.

type Restore

type Restore struct {
	DB *store.DB
}

Restore answers the operator's questions after a restore and performs the per-principal reconciliation.

func (*Restore) Reconcile

func (s *Restore) Reconcile(ctx context.Context, target domain.PrincipalID) (Status, error)

Reconcile commits ONE principal's re-activation and records it.

The signature is the guarantee the ADR asks for: one principal id in, one answer out. A caller wanting to reconcile twenty principals calls this twenty times and leaves twenty audit events behind, which is the intended cost — a single "reconcile everything" would turn an informed assertion about each identity into a keystroke.

func (*Restore) Status

func (s *Restore) Status(ctx context.Context) (Status, error)

Status reads the instance's restore posture.

type RestoreResult

type RestoreResult struct {
	Revision int64
	Changes  []StagedChange
	Preview  ImpactPreview
}

RestoreResult is a restore request's ordinary working-state output. The caller must publish the returned version ids through the normal pipeline.

type Retention

type Retention struct {
	AuditPolicy store.AuditRetentionPolicy
	DB          *store.DB
	Diagnostics *Diagnostics
	Now         func() time.Time
	// AfterMarkCollected is a deterministic race-test seam. It runs inside the
	// collection transaction after the snapshot row is marked and locked, but
	// before value rows are deleted and the transaction commits.
	AfterMarkCollected func(context.Context, string) error
	// Backup is the resolved DR schedule the health verdicts reason against
	// (#145). The zero value means no export policy: the health read then
	// reports "not scheduled" rather than an RPO breach.
	Backup BackupPolicy
	// PKI, when set, supplies the private-PKI health counts (#154).
	PKI *store.PKIRuntime
}

Retention owns tenant policy settings and the scheduler's payload sweep.

func (*Retention) GetHealth

func (s *Retention) GetHealth(ctx context.Context, actor Actor) (PruneHealth, error)

GetHealth authorizes and audits the instance API read in one transaction.

func (*Retention) GetOrg

func (s *Retention) GetOrg(ctx context.Context, actor Actor, orgID domain.OrgID) (RetentionPolicy, error)

GetOrg reads the organization default. The schema default makes a freshly created organization keep-if-either(90 days, 10 revisions).

func (*Retention) GetProject

func (s *Retention) GetProject(ctx context.Context, actor Actor, scope domain.Scope) (ProjectRetention, error)

GetProject returns the project override when present, otherwise the live org default. Inheritance is evaluated at read time, so an org change immediately applies to every unmodified project.

func (*Retention) LastPruneSuccess

func (s *Retention) LastPruneSuccess(ctx context.Context) (time.Time, bool, error)

LastPruneSuccess returns the persisted health timestamp. false means this datastore has never completed a payload prune. It is the scheduler's per-job success probe.

func (*Retention) OperationalHealth

func (s *Retention) OperationalHealth(ctx context.Context) (PruneHealth, error)

OperationalHealth reads scheduler health for local operational surfaces (doctor, /metrics). One transaction under scheduler authority reads both the last-prune timestamp and the per-project storage high-water (#185).

func (*Retention) SetOrg

func (s *Retention) SetOrg(ctx context.Context, actor Actor, orgID domain.OrgID, want RetentionPolicy) (RetentionPolicy, error)

SetOrg changes the organization cap and records the security event in the same transaction. Unlimited is an explicit mode; its dormant bounded values retain the previous values so switching back never invents a new policy.

func (*Retention) SetProject

func (s *Retention) SetProject(ctx context.Context, actor Actor, scope domain.Scope, want *RetentionPolicy) (ProjectRetention, error)

SetProject writes a bounded override, or nil to resume inheritance. Every override is capped by both organization dimensions before any write occurs.

func (*Retention) Sweep

func (s *Retention) Sweep(ctx context.Context) (int64, error)

type RetentionConsequence

type RetentionConsequence = store.RetentionConsequence

RetentionConsequence intentionally shares a store-owned type with transport mapping. This sanctioned seam follows the system-architecture ADR; boundary_test.go enforces that handlers never import internal/store directly.

type RetentionPolicy

type RetentionPolicy struct {
	Unlimited     bool
	MaxAge        time.Duration
	LastRevisions int64
}

RetentionPolicy keeps a payload when either bound still admits it. Unlimited is valid only for an organization policy.

type RetiringScope

type RetiringScope struct {
	Purpose          string
	OrgID            string
	ProjectID        string
	OpenableVersions int
}

RetiringScope names a DEK scope that still carries a superseded (retiring) version — one reencrypt has not yet cleared. OpenableVersions > 1 is the signal: a fully-reencrypted scope has exactly one openable version (active).

type Reveal

type Reveal struct {
	DB   *store.DB
	Auth *Auth
}

Reveal is the reveal guard's read surface. It is its own service rather than a method on Values because its formula is `read(E)` — a principal who may see an environment may see whether disclosing there will prompt them, which is not itself a disclosure — and because the browser calls it on paths where no value is being read at all (opening the ceremony modal, rendering the countdown chip after a remask).

func (*Reveal) Window

func (s *Reveal) Window(ctx context.Context, actor Actor, scope domain.Scope) (RevealWindow, error)

Window resolves the guard's state for one environment.

type RevealWindow

type RevealWindow struct {
	// DeveloperCredentialMaxLifetimeSeconds resolves the fixed lifetime before
	// human consent without requiring instance configuration privileges.
	DeveloperCredentialMaxLifetimeSeconds int64
	// EffectiveWindowSeconds is the environment's resolved window: its own
	// override, the protected cap, or the instance default. `0` means every
	// disclosure takes its own ceremony.
	EffectiveWindowSeconds int
	// Protected is the environment's protected flag. It is reported alongside
	// the window rather than folded into it because the UI states WHY the
	// window is 0, and "this environment is protected" is a different sentence
	// from "the window is set to 0".
	Protected bool
	// TOTPOffered is false exactly where the effective window is 0: TOTP
	// cannot bind a challenge to the enumerated unit, so it cannot honour a
	// per-disclosure gate, and the ceremony modal must not offer it there.
	// This is the [E2E] half of mvp-boundary A5 made a server fact rather than
	// a client convention.
	TOTPOffered bool
	// Live says a window is open for this session and environment right now.
	// When it is false the next disclosure prompts; when it is true the
	// disclosure proceeds and slides the window.
	Live bool
	// ExpiresAt is when the live window lapses — the countdown chip's input.
	// Zero when no window is live.
	ExpiresAt time.Time
	// SingleDecision marks a 0-window WebAuthn window: it authorizes exactly
	// the keys its ceremony enumerated and is spent by one decision, so the UI
	// must not present it as a standing window with a countdown.
	SingleDecision bool
	// CanReveal is whether this principal satisfies `read ∧ reveal` here.
	//
	// It is an AFFORDANCE, never a decision — the chokepoint still judges every
	// disclosure — and it is what makes write-only editing a first-class path
	// rather than a guess. `edit` without `reveal` is a supported state the
	// permission model refuses to reject ("write-only replacement (blind
	// rotation)… the UI MUST support the write-only editing path"), so the
	// editor has to offer a replacement field with honest microcopy to someone
	// who cannot read what is there. Deriving that from whether a cell happens
	// to be revealed on screen would make it a function of what the human last
	// clicked.
	CanReveal bool
}

RevealWindow reports the reveal guard's state for one environment, for the acting session.

It exists because the window gates the PROMPT: the browser has to decide whether to run a ceremony before a disclosure, and which factors that ceremony may offer, and it must not recompute that policy itself. The server owns "is this environment capped at 0", "is a window live right now", and "may TOTP open one here" — the client renders the answer.

Nothing here is a disclosure. The effective window and the protected flag are project settings, and the live window is the caller's own session state; a caller who cannot `read` the environment never gets this far, because the formula is `read(E)` and the chokepoint answers the uniform nonexistent.

type RevisionDetail

type RevisionDetail struct {
	RevisionView
	ChangeToken string
	// Keys is the delivered key set of that revision -- names, classifications
	// and write-presence. It is the snapshot's own key set, under the schema
	// revision the snapshot pinned, so a later rename or key deletion does not
	// rewrite what history says was delivered.
	Keys []SnapshotKey
}

RevisionDetail is one revision, plus the change token derived for it under the CURRENT root token key.

type RevisionDiff

type RevisionDiff struct {
	LeftRevision, RightRevision int64
	Items                       []RevisionDiffRow
}

type RevisionDiffRow

type RevisionDiffRow struct {
	KeyID, Name, Classification, Status string
	Revealed                            bool
	Before, After                       *string
}

type RevisionView

type RevisionView struct {
	Revision        int64
	SchemaRevision  int64
	PublishedBy     string
	PublishedByName string
	PublishedAt     time.Time
	ChangedKeys     []ChangedKey
	// PayloadPresent is the collection bit (#52/#53). Lineage outlives its
	// payload, so a history entry says which of the two it still has -- and a
	// surface that offers diff, restore or pin on a collected revision would be
	// offering an act the service refuses. CollectedPolicy is the policy
	// stamped at collection, empty while the payload is present; it is what the
	// named refusal reports forever.
	PayloadPresent  bool
	CollectedPolicy string
}

RevisionView is one entry of an environment's history. It is LINEAGE: a number, who published it, when, what it pinned, and which keys moved. No value in any form, which is what lets lineage be retained forever while payloads are collected by policy.

type Revisions

type Revisions struct {
	DB      *store.DB
	Keyring *crypto.Keyring
	// Advisory receives the metadata-only live-update events, AFTER commit.
	// Nil disables the channel entirely, which is safe by construction:
	// correctness never depends on delivery (revision-model ADR, Live updates).
	Advisory *Advisory
	// Auth supplies the reveal guard for the one disclosing method here,
	// Export. Nil refuses every disclosure loudly.
	Auth *Auth
	// Budget applies the § 179 expensive-path concurrency bounds: publish 4 per
	// org, values export 2 per org / 6 per instance. Nil disables it. The
	// per-principal rate half of these two categories is deferred (the principal
	// resolves inside the transaction; see budget.go).
	Budget *Budget
	Now    func() time.Time
	// PublishProbe is the service-layer conformance seam for forcing two real
	// publish transactions to overlap around the project lock. Production
	// leaves it nil; it decides no behavior and sees no material.
	PublishProbe PublishConformanceProbe
	// ProjectStorageHighWater overrides the per-project storage high-water for
	// the cross-engine conformance test, which cannot seed 4 GiB. Zero (the
	// production default) means MaxProjectStorageBytes; the override can only
	// TIGHTEN the bound — a value at or above MaxProjectStorageBytes is ignored,
	// so no misconfiguration can relax the ops-spec refusal in production.
	ProjectStorageHighWater int64
}

Revisions owns the publish pipeline, the revision history, and the matrix signals derived from both.

func (*Revisions) Diff

func (s *Revisions) Diff(ctx context.Context, actor Actor, scope domain.Scope, leftRevision, rightRevision int64, keyID string) (RevisionDiff, error)

Diff reads one transaction's two retained snapshots. keyID selects the only key whose plaintext may be disclosed; empty means config-only comparison. Secret equality is never computed until authorization and ceremony complete.

func (*Revisions) ExportWithParameters

func (s *Revisions) ExportWithParameters(ctx context.Context, actor Actor, scope domain.Scope, revision int64, reveal bool, supplied map[string]string) ([]ExportedValue, int64, error)

ExportWithParameters is the bulk-disclosure verb: the resolved snapshot of one environment, from committed state, never from live values.

FORMULA, stated separately because the capabilities imply nothing about each other: current material is `read(E)` and `reveal(E)`; historical material -- any revision that is not the latest -- is `read(E)` and `reveal-history(E)`. A human session additionally runs the ceremony, which enumerates exactly the key set the export covers before any ciphertext is opened, and one audit event is written per disclosed key. Never "exported N secrets" as one row.

func (*Revisions) History

func (s *Revisions) History(ctx context.Context, actor Actor, scope domain.Scope, beforeRevision int64, limit int) ([]RevisionView, error)

History lists one page of an environment's revisions, newest first: the revisions strictly below beforeRevision (HistoryFromNewest for the first page), at most limit of them. A caller continues from the smallest revision it received. History is only ever read a page at a time: the page's headers come from one keyset read and the page's lineage from one range read, so the cost of a page does not grow with the environment's lifetime history.

func (*Revisions) HistoryPage

func (s *Revisions) HistoryPage(ctx context.Context, actor Actor, scope domain.Scope, beforeRevision int64, limit int) ([]RevisionView, error)

HistoryPage is the bounded keyset read behind hikyo_list_revisions. It is History under its MCP-facing name: the same page shape, the same stable order (the UNIQUE revision, descending) and the same first-page sentinel.

func (*Revisions) PendingDrafts

func (s *Revisions) PendingDrafts(ctx context.Context, actor Actor, scope domain.Scope) ([]PendingDraft, error)

PendingDrafts lists only the caller's own drafts in one environment. The owner and environment predicates live in SQL; this layer joins catalogue names/classifications and opens config sets under the ordinary read gate. Secret bytes are evaluated only for the owner-only advisory, never returned. Only config previews carry plaintext on this endpoint.

func (*Revisions) PendingDraftsPage

func (s *Revisions) PendingDraftsPage(ctx context.Context, actor Actor, scope domain.Scope, afterKeyID string, limit int) ([]PendingDraft, error)

PendingDraftsPage is the bounded keyset read behind hikyo_list_pending_changes. The owner is the caller resolved inside the transaction, and the stable order is the UNIQUE draft key_id; afterKeyID is "" for the first page. `config` draft plaintext may appear; a `secret` or unset draft never carries material.

func (*Revisions) PublishPlanned

func (s *Revisions) PublishPlanned(ctx context.Context, actor Actor, scope domain.Scope, request PublishRequest) (PublishResult, error)

Publish commits a selection of the caller's own pending changes.

The whole operation runs in ONE serializable transaction that also holds the per-project lock: conflict checking, closure, validation, snapshot construction, revision allocation and the latest-pointer advance are all inside it. Without that, two publishes computed from the same baseline can both commit and the later materialization silently reverts the other's key -- unique revision numbers alone do not linearize the outcome.

SELECTION ISOLATION: each affected environment's snapshot is computed from the last published state plus the SELECTED versions only. The publisher's unselected drafts and every other principal's are invisible to it, so the materialized snapshot always corresponds to a state the publisher previewed. PublishPlanned commits a selection after checking its bound preview and any protected-environment confirmation inside the same serialized transaction.

func (*Revisions) Restore

func (s *Revisions) Restore(ctx context.Context, actor Actor, scope domain.Scope, revision int64, keyName string) (RestoreResult, error)

Restore stages the two-way difference between one historical snapshot and the current published state. keyName narrows the comparison to one key; an empty name compares the whole environment.

func (*Revisions) RotateScanningKey

func (s *Revisions) RotateScanningKey(ctx context.Context, actor Actor) (ScanningKeyRotation, error)

RotateScanningKey mints a new scanning-fingerprint key, retires the old one, drops EVERY dismissal row, and adopts the new key for every subsequent fingerprint — all in one transaction.

It is the exact twin of RotateTokenKey (secret-scanning ADR section 4), and the same reasoning applies: a scanning key is a tier-3 key alongside the DEKs, so `rotate-dek` is its authority and inventing a sixth atom would amend a locked ADR to say what an existing one already says. What differs is the dismissal drop: outright replacement makes every stored fingerprint unrecomputable, so keeping the rows would silently suppress warns that must now re-fire — dropping them is the safe direction, and it rides the same transaction so no crash window leaves the key rotated but the rows alive.

func (*Revisions) RotateTokenKey

func (s *Revisions) RotateTokenKey(ctx context.Context, actor Actor) (TokenKeyRotation, error)

RotateTokenKey mints a new root token key, retires the old one, and adopts the new one for every subsequent derivation.

WHAT IT DOES NOT TOUCH, which is the whole acceptance criterion (mvp-boundary C4, encryption-model ADR CI invariant 15): no snapshot's content, no revision number, and no pinned input revision moves. It cannot, because a change token is not stored anywhere -- it is derived at read from the live key over the snapshot's delivery manifest. The encryption-model ADR's "invalidate the cache and recompute eagerly" protocol exists because a cached token would otherwise keep serving the old value; there is no cache here, so adopting the handle IS the rotation, atomically, with nothing to resume after a crash.

It rides the `rotate-dek` capability. The permission-model ADR's capability set is CLOSED and names four rotation atoms for five rotation verbs; the token key is a tier-3 key alongside the DEKs, wrapped by the same master, retired through the same one-active-per-scope index -- so `rotate-dek` is the tier-3 rotation authority, and inventing a fifth atom would amend a locked ADR to say what an existing one already says.

func (*Revisions) Show

func (s *Revisions) Show(ctx context.Context, actor Actor, scope domain.Scope, revision int64) (RevisionDetail, error)

Show reads one revision, or the latest when revision is 0.

It returns the change token, and that is the point of the verb for a machine caller: the token is derived here from the live root token key, so `rotate-token-key` moves it while the revision number, the pinned schema revision and every pinned value-entry revision stay exactly where they are.

func (*Revisions) Signals

func (s *Revisions) Signals(ctx context.Context, actor Actor, scope domain.Scope) (EnvironmentSignals, error)

Signals computes the matrix's two signals for one environment.

It is a pure read over drafts and lineage: nothing is stored, so "a value publish recomputes matrix signals for exactly the touched environments" (mvp-boundary C2) holds structurally rather than by bookkeeping. An untouched environment's revision did not move and its lineage gained no rows, so its signals cannot have changed; a touched one's did, so they did.

func (*Revisions) Watch

func (s *Revisions) Watch(ctx context.Context, actor Actor, scope domain.Scope) (<-chan AdvisoryEvent, error)

Watch subscribes to the project's advisory events, authorized twice: once at connect, for the project, and once PER EVENT against the project or environment that event names. Events the recipient may not see are dropped, and an event reduced to nothing is never sent.

The returned channel closes when ctx ends, when the subscriber falls behind, when its credential no longer authenticates, or when the instance shuts down. It never carries an error: a stream that dies is a reconnect, and a reconnect is a refetch.

type RootKeyRotation

type RootKeyRotation struct {
	Phase string
	Epoch uint32
}

RootKeyRotation is one phase of `rotate-root-key`: the phase run and the epoch it concerns (the new epoch for prepare/verify, the surviving epoch after finalize).

type RootKeyRotationPhase

type RootKeyRotationPhase string

RootKeyRotationPhase selects one phase of the crash-safe root rotation.

const (
	RootRotatePrepare  RootKeyRotationPhase = "prepare"
	RootRotateVerify   RootKeyRotationPhase = "verify"
	RootRotateFinalize RootKeyRotationPhase = "finalize"
)

type RootKeySource

type RootKeySource interface {
	// Current reads the primary root key (the one this instance boots under).
	Current(ctx context.Context) ([]byte, error)
	// Next reads the operator's NEW root key from its configured new-root
	// source, for rotate-root-key --prepare. It errors when no new-root source
	// is configured, so the request never carries key material.
	Next(ctx context.Context) ([]byte, error)
}

RootKeySource re-reads operator root key material from its configured source. The keyring never retains the root (it is zeroed after boot), so the two rotations that need it read it through this seam. Every returned buffer is the caller's to zero.

type RotateSSHCARequest

type RotateSSHCARequest struct {
	Algorithm      string
	PrivateKey     []byte
	OverlapSeconds *int64
}

RotateSSHCARequest rotates a CA to a new generated or imported key. A nil OverlapSeconds lasts until the latest expiry among the live certificates the active key signed (zero when there are none), capped at 30 days.

type RotateSession

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

RotateSession describes a live session whose bearer and factor projection are replaced in place. The caller must authenticate session inside the same transaction immediately before completion.

type Rotation

type Rotation struct {
	DB      *store.DB
	Keyring *crypto.Keyring
	// RootKey re-reads the operator root from its source on demand. The master
	// is wrapped by the root and the root is zeroed after boot, so master and
	// root rotation both re-read it here rather than holding it in memory. Nil
	// refuses those two rotations loudly.
	RootKey RootKeySource
	// Budget applies the §179 fail-closed default to master-key rewrapping and
	// root-key source I/O/hierarchy-lock contention. Nil disables limits only.
	Budget *Budget
	Now    func() time.Time
}

Rotation is the operator surface for the four key-hierarchy rotations that are not the token key (encryption-model ADR § Rotation): rotate-dek, reencrypt, rotate-master-key and rotate-root-key. Each is its own instance-level capability, never bundled, so the post-compromise recovery order can run each under a distinct authority. Token-key rotation lives on Revisions because it is coupled to the change-token cache; these four are pure crypto-hierarchy hygiene.

func (*Rotation) RotateDEK

func (s *Rotation) RotateDEK(ctx context.Context, actor Actor, scope DEKScope) (DEKRotation, error)

RotateDEK appends a new DEK version for one project or the instance scope. New writes seal under it immediately; ciphertext under the previous version stays readable until `reencrypt` walks it. This is the append half of the ADR's keyring semantics — free, and incomplete on its own.

func (*Rotation) RotateMasterKey

func (s *Rotation) RotateMasterKey(ctx context.Context, actor Actor) (MasterKeyRotation, error)

RotateMasterKey generates a new master key, re-wraps every tier-3 key under it, and retires the old master after a fenced check. It is step 2 of the post-compromise recovery order — an attacker who held process memory holds the master, so every DEK must be re-wrapped under a master they never saw.

It refuses while the root is dual-wrapped: the two rotations are mutually exclusive, and the operator runs `rotate-root-key --finalize` first.

func (*Rotation) RotateRootKey

func (s *Rotation) RotateRootKey(ctx context.Context, actor Actor, phase RootKeyRotationPhase) (RootKeyRotation, error)

RotateRootKey runs one phase of the crash-safe root rotation (encryption-model ADR § Rotation). No key material ever crosses the wire: prepare reads the NEW root from its server-side source and seals a second wrapper; verify re-reads the PRIMARY source and confirms the operator installed the new root there; finalize retires the old wrapper. A crash at any point leaves the instance bootable under either root until finalize.

type RuleSpec

type RuleSpec struct {
	Target     domain.PrincipalID
	Capability domain.Capability
	Org        domain.OrgID
	Where      domain.Where
}

RuleSpec names one rule: who gets which capability, where.

type RuleView

type RuleView struct {
	ID            string
	Principal     domain.PrincipalID
	PrincipalName string
	Capability    domain.Capability
	Org           domain.OrgID
	Where         domain.Where
	OtherProjects bool
	CreatedBy     domain.PrincipalID
	CreatedAt     time.Time
}

RuleView is one rule on the listing surface. On a project listing Where holds only the addressed project's part and OtherProjects reports that the rule also names projects the listing does not show. Environments and keys are ids (and folder paths): their names need `read`, which a member manager may not hold.

type Rules

type Rules struct {
	DB  *store.DB
	Now func() time.Time
}

Rules owns the rule surface.

func (*Rules) Create

func (s *Rules) Create(ctx context.Context, actor Actor, spec RuleSpec) (RuleView, error)

Create writes one rule. Manage access must cover its complete selector, and the grantor must hold the delegated capability throughout that selector. Existing org- and instance-scope managers retain the grant-unheld exception.

func (*Rules) List

func (s *Rules) List(ctx context.Context, actor Actor, scope domain.Scope) ([]RuleView, error)

List returns the rules in the addressed org, or those naming the addressed project (reading only that project's items), audited as a membership read like the grant listing.

func (*Rules) Replace

func (s *Rules) Replace(ctx context.Context, actor Actor, spec ReplaceRulesSpec) ([]RuleView, error)

Replace authorizes the entire batch against the original state. No mutation or session invalidation happens until every authorization has succeeded.

func (*Rules) Revoke

func (s *Rules) Revoke(ctx context.Context, actor Actor, org domain.OrgID, id string) error

Revoke removes one rule, killing its holder's sessions in the same transaction. A rule the caller cannot reach answers exactly like a missing one.

type RuntimeStatus

type RuntimeStatus struct {
	State string
	Phase string
}

RuntimeStatus is a closed public projection with no instance identifiers.

type SAMLMetadataDiff

type SAMLMetadataDiff struct {
	EndpointsAdded          []string
	EndpointsRemoved        []string
	CertsAddedFps           []string
	CertsRemovedFps         []string
	MetadataCertsAddedFps   []string
	MetadataCertsRemovedFps []string
	ValidUntil              *time.Time
}

SAMLMetadataDiff is the complete trust-material change shown before a provider mutation is applied. Empty collections are non-nil for stable JSON.

type SAMLMetadataRefreshInput

type SAMLMetadataRefreshInput struct {
	MetadataDocument      []byte
	ConfirmedFingerprints []string
	ConfirmedEndpoints    []string
}

type SAMLProviderInput

type SAMLProviderInput struct {
	DisplayName           string
	EntityID              string
	MetadataSource        string
	MetadataDocument      []byte
	MetadataURL           *string
	AssurancePolicy       *[]string
	AllowEmailNameID      bool
	ForceSignRequests     bool
	Enabled               bool
	ConfirmedFingerprints []string
	ConfirmedEndpoints    []string
}

type SAMLProviderMutationResult

type SAMLProviderMutationResult struct {
	Applied              bool
	Provider             *SAMLProviderView
	Diff                 SAMLMetadataDiff
	RequiredFingerprints []string
	RequiredEndpoints    []string
}

SAMLProviderMutationResult is both legs of the metadata ceremony. A false Applied value is a successful preview and guarantees that no state changed.

type SAMLProviderPatch

type SAMLProviderPatch struct {
	DisplayName       *string
	AssurancePolicy   *[]string
	AllowEmailNameID  *bool
	ForceSignRequests *bool
	Enabled           *bool
}

type SAMLProviderView

type SAMLProviderView struct {
	Slug                           string
	DisplayName                    string
	EntityID                       string
	ACSURL                         string
	SSORedirectURL                 string
	SigningCertificateFingerprints []string
	AssurancePolicy                *[]string
	AllowEmailNameID               bool
	ForceSignRequests              bool
	MetadataSource                 string
	MetadataURL                    *string
	MetadataSigned                 bool
	MetadataSigningFingerprint     *string
	MetadataValidUntil             *time.Time
	Warnings                       []SAMLProviderWarning
	Enabled                        bool
	RowVersion                     int64
	CreatedAt                      time.Time
	UpdatedAt                      time.Time
	// contains filtered or unexported fields
}

type SAMLProviderWarning

type SAMLProviderWarning struct {
	Code        string
	Severity    string
	Message     string
	EffectiveAt time.Time
	Fingerprint *string
}

SAMLProviderWarning is the server-authoritative provider health result used by admin views and doctor. EffectiveAt is the metadata/certificate boundary that caused the warning; Fingerprint is present only for certificate rows.

type SAMLProviders

type SAMLProviders struct {
	DB             *store.DB
	Keyring        *wencrypto.Keyring
	ExternalOrigin string
	Now            func() time.Time
	// contains filtered or unexported fields
}

SAMLProviders is instance-scoped SAML provider administration.

func NewSAMLProviders

func NewSAMLProviders(db *store.DB, keyring *wencrypto.Keyring, externalOrigin string) *SAMLProviders

NewSAMLProviders builds the production SAML provider service. Metadata URL retrieval always enters through the guarded transport assembled here.

func (*SAMLProviders) CompromiseRetireSPKey

func (s *SAMLProviders) CompromiseRetireSPKey(ctx context.Context, actor Actor, fingerprint string) (SAMLSPKeyView, error)

func (*SAMLProviders) Delete

func (s *SAMLProviders) Delete(ctx context.Context, actor Actor, slug string) error

func (*SAMLProviders) Get

func (s *SAMLProviders) Get(ctx context.Context, actor Actor, slug string) (SAMLProviderView, error)

func (*SAMLProviders) List

func (s *SAMLProviders) List(ctx context.Context, actor Actor) ([]SAMLProviderView, error)

func (*SAMLProviders) ListSPKeys

func (s *SAMLProviders) ListSPKeys(ctx context.Context, actor Actor) ([]SAMLSPKeyView, error)

func (*SAMLProviders) Patch

func (s *SAMLProviders) Patch(ctx context.Context, actor Actor, slug string, patch SAMLProviderPatch) (SAMLProviderView, error)

func (*SAMLProviders) Put

func (*SAMLProviders) RefreshMetadata

func (s *SAMLProviders) RefreshMetadata(ctx context.Context, actor Actor, slug string, input SAMLMetadataRefreshInput) (SAMLProviderMutationResult, error)

func (*SAMLProviders) RetireSPKey

func (s *SAMLProviders) RetireSPKey(ctx context.Context, actor Actor, fingerprint string) error

func (*SAMLProviders) RotateSPKey

func (s *SAMLProviders) RotateSPKey(ctx context.Context, actor Actor) (SAMLSPKeyView, error)

type SAMLSPKeyView

type SAMLSPKeyView struct {
	Fingerprint string
	State       string
	CreatedAt   time.Time
}

SAMLSPKeyView exposes only public key lifecycle metadata. Private material never crosses the service boundary.

type SAMLStartResult

type SAMLStartResult struct {
	RedirectURL     string
	InitiatorCookie string
	Purpose         string
}

SAMLStartResult carries the redirect and the anonymous-login binding value. Transport returns only RedirectURL in JSON and sets InitiatorCookie as the path-scoped Secure/HttpOnly/SameSite=None cookie the ACS must present.

type SCIM

type SCIM struct {
	DB  *store.DB
	Now func() time.Time

	// Auth is the reauthentication library. Minting a provisioning credential
	// is `manage-members(org)` ∧ REAUTHENTICATION (§7): a stolen elevated
	// session must not be able to issue a year-long bearer without re-proving
	// the human. Nil means the below-the-network paths only, and a network
	// mint with no Auth fails closed rather than silently skipping the gate.
	Auth *Auth

	// CredentialTTL is the lifetime ceiling every provisioning credential is
	// clamped to. AllowIndefinite is the instance opt-in that permits a
	// credential with no ceiling at all; it is default-off, and a request for
	// an indefinite credential is refused by name without it.
	CredentialTTL   time.Duration
	AllowIndefinite bool

	// Staleness is how long a binding may go without IdP contact before the
	// binding surface shows the warning. Nothing self-heals from it and no
	// grant expires because of it: converting an IdP outage into org-wide
	// revocation is the scrub-on-timer failure the ADR rejects by name.
	Staleness time.Duration

	// MaxPageSize bounds a SCIM ListResponse. A request above it is clamped,
	// not refused: RFC 7644 §3.4.2.4 makes `count` a request, and the server's
	// bound is the answer.
	MaxPageSize int
}

SCIM owns the provisioning surface.

func (*SCIM) Authenticate

func (s *SCIM) Authenticate(ctx context.Context, actor Actor, org domain.OrgID, bindingID string) error

Authenticate runs the wire gate and nothing else: credential, binding-path match, `scim-provision(org)`, provider liveness. The transport calls it when a request FAILED TO PARSE, so an unknown, revoked or wrong-binding credential still answers 401 rather than being told its body was malformed — a 400 to an unauthenticated caller confirms the binding exists.

It costs an extra transaction only on the malformed path; a request that parses is authenticated by the operation itself.

func (*SCIM) CreateBinding

func (s *SCIM) CreateBinding(ctx context.Context, actor Actor, org domain.OrgID, in SCIMBindingInput) (SCIMBindingView, error)

CreateBinding creates the per-org binding, its provisioning connection, and the connection's structural `scim-provision` grant — one transaction, because a connection without its grant is a principal that can do nothing and a grant without its connection is a row no origin holds.

func (*SCIM) CreateGroup

func (s *SCIM) CreateGroup(ctx context.Context, actor Actor, org domain.OrgID, bindingID string, in DesiredGroup) (SCIMGroupResource, error)

CreateGroup mints a group and applies any mapping rows already pointing at the id — normally none, because mapping rows reference the id minted HERE.

func (*SCIM) CreateMapping

func (s *SCIM) CreateMapping(ctx context.Context, actor Actor, org domain.OrgID, bindingID string, spec SCIMMappingSpec) (SCIMMappingResult, error)

CreateMapping adds a mapping row and applies it IMMEDIATELY to the group's current members, in the authoring transaction (§3).

func (*SCIM) CreateUser

func (s *SCIM) CreateUser(ctx context.Context, actor Actor, org domain.OrgID, bindingID string, in DesiredUser) (SCIMUserResource, error)

CreateUser is §5.2: an account with its external identity ALREADY BOUND — no invitation token, no credential-establishment authority, no session, no assurance — and ZERO grants beyond what the user's current group memberships and the mapping table produce.

Idempotent attach, no cross-org oracle (§5.2 under the #23 amendment): if the asserted identity already exists instance-wide, this attaches that account. Both legs follow ONE query path and return a byte-shape-identical resource, so a caller cannot tell a fresh create from an attach — which is the whole point, because "it existed already" would otherwise be a cross-org oracle.

func (*SCIM) DeleteBinding

func (s *SCIM) DeleteBinding(ctx context.Context, actor Actor, org domain.OrgID, id string) error

DeleteBinding runs §6's atomic state machine, in the ADR's order:

  1. revoke every credential — no new wire transaction can begin, and an in-flight one fails at its next proof;
  2. release every `scim` origin the binding holds, under §2.4 — lockout conversion applies, and any resulting `lockout-retention` origins SURVIVE the binding with their cause recorded, still cured by adding another `manage-members` holder;
  3. retire the provisioning connection: release the `structural(binding)` origin, revoking the `scim-provision` grant, and delete the principal — atomically with the directory resources, mapping table and binding row;
  4. identity links SURVIVE. They are account property, exactly as they would be had the user been invited; unlinking remains the account-security mutation it always was, and nothing here touches it.

func (*SCIM) DeleteGroup

func (s *SCIM) DeleteGroup(ctx context.Context, actor Actor, org domain.OrgID, bindingID, id string) error

DeleteGroup releases that group's origins for every member and flips every referencing mapping row to INERT with an attention state — the row is never silently removed, because a human has to decide whether it should point at a live group or go away (§5.4).

func (*SCIM) DeleteMapping

func (s *SCIM) DeleteMapping(ctx context.Context, actor Actor, org domain.OrgID, bindingID string, spec SCIMMappingSpec) (SCIMMappingResult, error)

DeleteMapping removes one addressed row and releases every origin keyed on it, in the authoring transaction (§4): "the org admin is never stuck behind an IdP they don't control".

func (*SCIM) DeleteUser

func (s *SCIM) DeleteUser(ctx context.Context, actor Actor, org domain.OrgID, bindingID, id string) error

DeleteUser is the same release plus removal from the binding's directory, INCLUDING removal of every member reference to that user from the binding's groups, in the same transaction — so a stale reference cannot exist and a re-create after DELETE gets a fresh id with nothing pointing at the old one.

The account and its identity links are instance-level and SURVIVE: other orgs' memberships and other providers are not this IdP's to kill.

func (*SCIM) DirectoryGroups

func (s *SCIM) DirectoryGroups(ctx context.Context, actor Actor, org domain.OrgID, bindingID string) ([]SCIMDirectoryGroup, error)

DirectoryGroups is `hikyo scim group list <binding>`.

func (*SCIM) DirectoryUsers

func (s *SCIM) DirectoryUsers(ctx context.Context, actor Actor, org domain.OrgID, bindingID string) ([]SCIMDirectoryUser, error)

DirectoryUsers is `hikyo scim user list <binding>`.

func (*SCIM) Discovery

func (s *SCIM) Discovery(ctx context.Context, actor Actor, org domain.OrgID, bindingID string) ([]scimproto.ExtensionDecl, error)

Discovery serves the three static documents. They run under the binding's authentication, admission and serialization, and they record contact — a probe IS the identity provider reaching this server — but they emit NOTHING. §10: the discovery endpoints "carry no tenant data; they are the one SCIM surface annotated `audited: none`-equivalent by explicit registry annotation on their probe class, not silence". The annotation is the name-pinned exemption entry (internal/isolation/testdata/audited_exemptions.json) for `scim-discovery.read` and for each of the three routes; a `directory_read` per probe would record the server's own manual being read, and would bury the reads that ARE tenant data under a connector's polling.

Nor does it reconcile attention: a configuration fetch is not a re-assertion cycle, so it must not clear the post-restore state (§9.1's exit is re-mint PLUS a completed cycle) and must not lower a staleness warning that no directory traffic has earned. It returns the binding's DECLARED schema extensions, because the three documents are per-binding truth: a binding whose subject source lives under a custom URN describes that URN, and one that does not, does not.

func (*SCIM) GetBinding

func (s *SCIM) GetBinding(ctx context.Context, actor Actor, org domain.OrgID, id string) (SCIMBindingView, error)

GetBinding returns one binding. It deliberately does NOT require a live provider: "state is preserved for repair" is not preserved by a surface that refuses to show the state (§1).

func (*SCIM) GetCredential

func (s *SCIM) GetCredential(ctx context.Context, actor Actor, org domain.OrgID, bindingID, id string) (SCIMCredentialView, error)

GetCredential returns one credential by id.

func (*SCIM) GetGroup

func (s *SCIM) GetGroup(ctx context.Context, actor Actor, org domain.OrgID, bindingID, id string) (SCIMGroupResource, error)

GetGroup returns one group with its member references.

func (*SCIM) GetUser

func (s *SCIM) GetUser(ctx context.Context, actor Actor, org domain.OrgID, bindingID, id string) (SCIMUserResource, error)

GetUser and ListUsers are authenticated machine READS. They are events too, in the `access` retention class: the ADR withdraws by name the earlier claim that every SCIM operation is mutating.

func (*SCIM) ListBindings

func (s *SCIM) ListBindings(ctx context.Context, actor Actor, org domain.OrgID) ([]SCIMBindingView, error)

ListBindings returns the org's bindings with their attention states, keeping the provider-availability and staleness states current in both directions.

func (*SCIM) ListCredentials

func (s *SCIM) ListCredentials(ctx context.Context, actor Actor, org domain.OrgID, bindingID string) ([]SCIMCredentialView, error)

ListCredentials returns the binding's credentials — ids and metadata only.

func (*SCIM) ListGroups

func (s *SCIM) ListGroups(ctx context.Context, actor Actor, org domain.OrgID, bindingID string, filter scimproto.Filter, page scimproto.Page) ([]SCIMGroupResource, int, error)

ListGroups answers the two Group filters. `displayName eq` is the probe both Okta and Entra issue to discover a group before creating or updating it, so it is load-bearing rather than a convenience.

func (*SCIM) ListMappings

func (s *SCIM) ListMappings(ctx context.Context, actor Actor, org domain.OrgID, bindingID string) ([]SCIMMappingView, error)

ListMappings returns the binding's mapping table.

func (*SCIM) ListUsers

func (s *SCIM) ListUsers(ctx context.Context, actor Actor, org domain.OrgID, bindingID string, filter scimproto.Filter, page scimproto.Page) ([]SCIMUserResource, int, error)

ListUsers answers the two User filters and the RFC's 1-based paging. An out-of-range page returns an empty resource list with a TRUTHFUL total.

func (*SCIM) MintCredential

func (s *SCIM) MintCredential(ctx context.Context, actor Actor, org domain.OrgID, bindingID string, indefinite bool, proof string) (SCIMMintResult, error)

MintCredential issues a NEW credential for the binding; several may be live at once with identical authority.

func (*SCIM) PageBound

func (s *SCIM) PageBound() int

PageBound is the server's `count` ceiling, so the transport clamps against the same number the service does.

func (*SCIM) PatchGroup

func (s *SCIM) PatchGroup(ctx context.Context, actor Actor, org domain.OrgID, bindingID, id string, commands []GroupPatchCommand) (SCIMGroupResource, error)

PatchGroup reduces the validated command sequence over stored desired state.

func (*SCIM) PatchUser

func (s *SCIM) PatchUser(ctx context.Context, actor Actor, org domain.OrgID, bindingID, id string, commands []UserPatchCommand) (SCIMUserResource, error)

PatchUser reduces the validated command sequence over stored desired state, then persists the one resulting resource.

func (*SCIM) ReplaceGroup

func (s *SCIM) ReplaceGroup(ctx context.Context, actor Actor, org domain.OrgID, bindingID, id string, desired DesiredGroup) (SCIMGroupResource, error)

ReplaceGroup is RFC replacement: omitted mutable attributes clear, and the member set is replaced wholesale.

func (*SCIM) ReplaceUser

func (s *SCIM) ReplaceUser(ctx context.Context, actor Actor, org domain.OrgID, bindingID, id string, desired DesiredUser) (SCIMUserResource, error)

ReplaceUser is RFC replacement (PUT): omitted mutable attributes clear to their defaults, `active` defaults TRUE — so an omitted `active` REACTIVATES, per the transition table — `userName` is required, the subject source is exempt from replacement (write-once), and `groups` is ignored on input.

func (*SCIM) RevokeCredential

func (s *SCIM) RevokeCredential(ctx context.Context, actor Actor, org domain.OrgID, bindingID, id string) error

RevokeCredential kills one credential. Revocation bites at the next request: the row is marked rather than deleted, so the verifier stays occupied and the id keeps naming a real thing on this surface.

func (*SCIM) Unsupported

func (s *SCIM) Unsupported(ctx context.Context, actor Actor, org domain.OrgID, bindingID, what string) error

Unsupported is the authenticated refusal of a feature this provider advertises as absent (§8). It authenticates and authorizes exactly like every other wire operation — so an unauthenticated caller gets the uniform refusal rather than a 501 that would confirm the binding exists — and then the transport renders HTTP 501 with the RFC error body.

func (*SCIM) UpdateMapping

func (s *SCIM) UpdateMapping(ctx context.Context, actor Actor, org domain.OrgID, bindingID string, spec SCIMMappingSpec) (SCIMMappingResult, error)

UpdateMapping retargets one addressed row's template in place. The row KEEPS its id, which is what makes narrowing precise: origins key on the row, so a delete-and-recreate would release every origin it holds and immediately recreate most of them — momentarily revoking capabilities that never stopped being granted, and logging their holders out for a bookkeeping change.

Widening creates the newly covered origins here and now; narrowing releases the no-longer-covered part under §2.4, in the same authoring transaction and with no IdP round-trip (§4).

type SCIMAttentionView

type SCIMAttentionView struct {
	State      string
	SubjectRef string
	Cause      string
	EnteredAt  time.Time
	// Remediation is server-authored: the surface must name what to do, not
	// only what is wrong.
	Remediation string
}

SCIMAttentionView is one raised attention state with its cause.

type SCIMBindingInput

type SCIMBindingInput struct {
	ProviderKind domain.ProviderKind
	ProviderSlug string
	// SubjectSource is the SCIM attribute path carrying identity material.
	// `userName` is refused by name.
	SubjectSource string
	// The SAML NameID profile. Presence is carried separately from value
	// because the injective encoder distinguishes an absent qualifier from an
	// empty one, and collapsing them would make two SAML subjects collide.
	NameIDFormat             string
	NameIDQualifier          string
	NameIDQualifierPresent   bool
	NameIDSPQualifier        string
	NameIDSPQualifierPresent bool
}

SCIMBindingInput is a binding as the caller declares it. Everything in it is immutable after creation: the subject source and NameID profile by §5.1, the provider reference because a binding holds a READ-ONLY reference to it.

type SCIMBindingView

type SCIMBindingView struct {
	ID                       string
	OrgID                    string
	ProviderKind             string
	ProviderSlug             string
	ProviderIssuer           string
	SubjectSource            string
	NameIDFormat             string
	NameIDQualifier          string
	NameIDQualifierPresent   bool
	NameIDSPQualifier        string
	NameIDSPQualifierPresent bool
	ConnectionPrincipalID    string
	LastContactAt            time.Time
	CreatedAt                time.Time
	Attention                []SCIMAttentionView
}

SCIMBindingView is one binding as the surface renders it, with the attention states that answer "what does SCIM think is wrong?" (§9).

type SCIMBlastWarning

type SCIMBlastWarning struct {
	Code     string
	Severity string
	Message  string
}

SCIMBlastWarning is server-authored consequence language for a mapping row (§3). It is authored HERE and not in a client because the rule the ADR locked is about what the human is told, and a client that renders its own wording is a second, unreviewed policy.

type SCIMCapabilityOrigin

type SCIMCapabilityOrigin struct {
	Capability string
	BindingID  string
	MappingID  string
	GroupID    string
}

SCIMCapabilityOrigin identifies the mapping source of an expanded capability. This is mapping intent, not a claim that any principal currently holds it.

type SCIMCredentialView

type SCIMCredentialView struct {
	ID         string
	BindingID  string
	CreatedAt  time.Time
	ExpiresAt  time.Time
	RevokedAt  time.Time
	LastUsedAt time.Time
	Live       bool
}

SCIMCredentialView is one credential as the surface renders it: ids and metadata, never token material — which does not exist to be listed, because only the verifier was ever stored.

type SCIMDirectoryGroup

type SCIMDirectoryGroup struct {
	ID          string
	DisplayName string
	ExternalID  string
	MemberCount int
	CreatedAt   time.Time
	UpdatedAt   time.Time
}

SCIMDirectoryGroup is one provisioned group with its member count.

type SCIMDirectoryUser

type SCIMDirectoryUser struct {
	ID         string
	UserName   string
	ExternalID string
	AccountID  string
	Active     bool
	Groups     []string
	CreatedAt  time.Time
	UpdatedAt  time.Time
	Attention  []SCIMAttentionView
}

SCIMDirectoryUser is one provisioned user as the ADMIN surface renders it. It carries the per-user attention flag the ADR requires after a deprovision: "IdP deprovisioned this user; manual grants remain."

type SCIMGroupResource

type SCIMGroupResource struct {
	ID          string
	ExternalID  string
	DisplayName string
	Members     []string
	CreatedAt   time.Time
	UpdatedAt   time.Time
}

SCIMGroupResource is one provisioned group as the wire renders it.

type SCIMMappingResult

type SCIMMappingResult struct {
	Mapping SCIMMappingView
	// Warnings is never nil on a create or widen: the consequence language is
	// part of the response, not an optional decoration a client may drop.
	Warnings []SCIMBlastWarning
	// MembersAffected and GrantsCreated report the immediate blast: a mapping
	// row applies to the group's CURRENT members in the authoring transaction,
	// so there is no "waits for the next push" gap to hide behind.
	MembersAffected int
	GrantsCreated   int
	OriginsReleased int
}

SCIMMappingResult is what a create or widen actually did, warnings included.

type SCIMMappingSpec

type SCIMMappingSpec struct {
	GroupID  string
	Template domain.Template
	// Scope inside the binding's org. Both empty is org scope, which is the
	// widest a binding can reach and therefore the one that must be asked for
	// explicitly rather than defaulted into.
	ProjectID string
	EnvID     string
}

SCIMMappingSpec addresses or declares one mapping row.

type SCIMMappingView

type SCIMMappingView struct {
	ID        string
	BindingID string
	GroupID   string
	Template  string
	ProjectID string
	EnvID     string
	Inert     bool
	CreatedAt time.Time
	// Capabilities is what this row expands into — the ADR's "expansion at sync
	// time is expansion at grant time", made visible so a reader does not have
	// to know the template table by heart.
	Capabilities      []string
	CapabilityOrigins []SCIMCapabilityOrigin
}

SCIMMappingView is one mapping row as the surface renders it.

type SCIMMintResult

type SCIMMintResult struct {
	Credential SCIMCredentialView
	// Token is returned exactly once, to exactly one caller. Nothing persists
	// it; the store holds only its SHA-256 verifier.
	Token string
	// Rotated reports that this mint JOINED an already-live credential rather
	// than being the binding's first. That is what overlap rotation is, and it
	// is the difference between the two audit events.
	Rotated bool
}

SCIMMintResult carries the display-once value beside the row it belongs to.

type SCIMUserResource

type SCIMUserResource struct {
	ID         string
	ExternalID string
	UserName   string
	Active     bool
	Groups     []string
	Attributes map[string]any
	// Schemas is the `schemas` array this resource declares: the core User
	// schema plus every extension THIS BINDING declared that the resource
	// actually carries. It is computed here, beside the binding, rather than
	// in the transport — the transport cannot know what a binding declared,
	// and a resource declaring a schema discovery does not describe is the
	// half-implemented state §8 forbids.
	Schemas   []string
	CreatedAt time.Time
	UpdatedAt time.Time
}

SCIMUserResource is one provisioned user as the wire renders it.

type SSH

type SSH struct {
	DB      *store.DB
	Auth    *Auth
	Keyring *hcrypto.Keyring
	Budget  *Budget
	Runtime *store.SSHRuntime
	Now     func() time.Time
}

SSH owns the SSH user-certificate surface (#155): environment-scoped CAs (generated or imported, private key sealed under the project DEK and never returned), profiles that bound what a certificate may say and who may ask, issuance, revocation, the host trust bundle and the Key Revocation List. Design: docs/handoff/155-ssh-certificates.md.

func (*SSH) CreateCA

func (s *SSH) CreateCA(ctx context.Context, actor Actor, scope domain.Scope, req CreateSSHCARequest) (SSHCAView, error)

func (*SSH) CreateProfile

func (s *SSH) CreateProfile(ctx context.Context, actor Actor, scope domain.Scope, req SSHProfileRequest) (SSHProfileView, error)

func (*SSH) DeleteCA

func (s *SSH) DeleteCA(ctx context.Context, actor Actor, scope domain.Scope, caID string) error

DeleteCA tombstones a CA and destroys its signing material. This is record deletion, not revocation: certificates it signed stay valid on any host that still lists its keys in TrustedUserCAKeys until they expire.

func (*SSH) DeleteProfile

func (s *SSH) DeleteProfile(ctx context.Context, actor Actor, scope domain.Scope, profileID string, revokeIssued bool) (int, error)

DeleteProfile tombstones a profile (record deletion). With revokeIssued it also revokes every live certificate issued through it; without, those certificates stay valid until they expire. It returns the revoked count.

func (*SSH) Gauges

func (s *SSH) Gauges(ctx context.Context) (active, krlEntries int64, err error)

SSHGauges is the /metrics source.

func (*SSH) GetCA

func (s *SSH) GetCA(ctx context.Context, actor Actor, scope domain.Scope, caID string) (SSHCAView, error)

func (*SSH) GetCertificate

func (s *SSH) GetCertificate(ctx context.Context, actor Actor, scope domain.Scope, certID string) (SSHCertificateView, error)

func (*SSH) GetProfile

func (s *SSH) GetProfile(ctx context.Context, actor Actor, scope domain.Scope, profileID string) (SSHProfileView, error)

func (*SSH) Issue

func (s *SSH) Issue(ctx context.Context, actor Actor, scope domain.Scope, req IssueSSHCertificateRequest) (SSHIssueResult, error)

func (*SSH) KRL

func (s *SSH) KRL(ctx context.Context, actor Actor, scope domain.Scope, caID string) ([]byte, error)

KRL renders the CA's OpenSSH Key Revocation List: revoked, unexpired serials signed by keys hosts still trust. Over its bound it fails loud.

func (*SSH) ListCAs

func (s *SSH) ListCAs(ctx context.Context, actor Actor, scope domain.Scope) ([]SSHCAView, error)

func (*SSH) ListCertificates

func (s *SSH) ListCertificates(ctx context.Context, actor Actor, scope domain.Scope) ([]SSHCertificateView, error)

func (*SSH) ListProfiles

func (s *SSH) ListProfiles(ctx context.Context, actor Actor, scope domain.Scope) ([]SSHProfileView, error)

func (*SSH) RetireCAKey

func (s *SSH) RetireCAKey(ctx context.Context, actor Actor, scope domain.Scope, caID, keyID string) (SSHCAView, error)

RetireCAKey ends a retiring key's overlap now: hosts drop it on their next trust-bundle refresh.

func (*SSH) RevokeCertificate

func (s *SSH) RevokeCertificate(ctx context.Context, actor Actor, scope domain.Scope, certID string) (SSHCertificateView, error)

RevokeCertificate adds a certificate to its CA's KRL. The requester may revoke its own certificate; anyone else needs manage-identities over the project. Revoking an already-revoked certificate is a no-op success.

func (*SSH) RotateCA

func (s *SSH) RotateCA(ctx context.Context, actor Actor, scope domain.Scope, caID string, req RotateSSHCARequest) (SSHCAView, error)

func (*SSH) RunSweep

func (s *SSH) RunSweep(ctx context.Context) (int, error)

RunSweep re-decides every live certificate's requester authority and revokes, durably and with a system audit row, each whose requester was deleted, lost its grant, or was removed from the profile. A transient error never revokes: only a definite refusal does. It returns how many it revoked.

func (*SSH) TrustedKeys

func (s *SSH) TrustedKeys(ctx context.Context, actor Actor, scope domain.Scope, caID string) (string, error)

TrustedKeys renders the CA's trust bundle in TrustedUserCAKeys format: the active key and every retiring key still inside its overlap.

func (*SSH) UpdateProfile

func (s *SSH) UpdateProfile(ctx context.Context, actor Actor, scope domain.Scope, profileID string, req SSHProfileRequest) (SSHProfileView, error)

type SSHCAView

type SSHCAView struct {
	store.SSHCA
	// Trusted lists, in the same order as Keys, whether hosts following the
	// trust bundle accept that key now.
	Trusted []bool
}

SSHCAView is a CA and its keys, with each key's trust derived at read time.

type SSHCertificateView

type SSHCertificateView struct {
	store.SSHCertificate
	// Status is revoked | expired | untrusted | active.
	Status string
	// InKRL is whether the serial is published in the CA's revocation list.
	InKRL bool
}

SSHCertificateView is a certificate record with its derived status.

type SSHIssueResult

type SSHIssueResult struct {
	Certificate     SSHCertificateView
	CertificateText string
	PublicKey       string
	PrivateKey      string
}

SSHIssueResult carries a new certificate and, for a generated key, the private key exactly once.

type SSHProfileRequest

type SSHProfileRequest struct {
	CAID              string
	Name              string
	Principals        []string
	ForceCommand      string
	SourceAddresses   []string
	Extensions        []string
	KeyAlgorithms     []string
	DefaultTTLSeconds int64
	MaxTTLSeconds     int64
	Enabled           bool
	Requesters        []string
}

SSHProfileRequest creates or replaces a profile.

type SSHProfileView

type SSHProfileView struct{ store.SSHProfile }

SSHProfileView is one profile.

type ScanningKeyRotation

type ScanningKeyRotation struct {
	// Version is the scanning-fingerprint key's new version — operator-facing
	// bookkeeping only, like TokenKeyRotation.Version.
	Version uint32
	// DismissalsDropped is how many dismissal rows the rotation invalidated, so
	// the operator sees the blast radius of the re-fire the rotation caused.
	DismissalsDropped int64
}

ScanningKeyRotation is one `rotate-scanning-key`.

type SelfConfig

type SelfConfig struct {
	DB         *store.DB
	Keyring    *crypto.Keyring
	Auth       *Auth
	Budget     *Budget
	NodeID     string
	HAMode     bool
	Now        func() time.Time
	Seed       func() (map[string]string, error)
	SeedNode   func() (map[string]string, error)
	Installer  runtimeconfig.RuntimeInstaller
	Deployment BootstrapDeployment
	// contains filtered or unexported fields
}

SelfConfig connects an instance's ordinary encrypted project revisions to its runtime consumers. Seed is lazy: an adopted instance never reads or validates old process settings. Remote instances own separate services and datastores; this object coordinates only replicas of its local owner.

func (*SelfConfig) Adopt

func (*SelfConfig) Apply

Apply holds the preparation phase for at most 30 seconds. The independent runtime workers prepare each fixed participant. Only this final human transaction can commit the target; subsequent convergence is asynchronous.

func (*SelfConfig) AuthorizeRepairScope

func (s *SelfConfig) AuthorizeRepairScope(ctx context.Context, actor Actor, scope domain.Scope) error

AuthorizeRepairScope permits access to the bound configuration hierarchy while an application generation is unavailable. Normal operation-specific authorization still runs in the handler. A stale graph never gains general tenant access through this recovery exception.

func (*SelfConfig) Capture

func (s *SelfConfig) Capture(ctx context.Context) (*runtimeconfig.Bundle, error)

Capture performs only a metadata read on the request stack. It never mints runtime payload authority or silently falls back to a stale configuration.

func (*SelfConfig) CloseRuntime

func (s *SelfConfig) CloseRuntime() error

CloseRuntime disposes candidate resources after the app-owned worker has stopped. The currently installed application remains the supervisor's owner.

func (*SelfConfig) LoadRuntime

func (s *SelfConfig) LoadRuntime(ctx context.Context) error

LoadRuntime is a boot/worker entrypoint, never an HTTP handler operation.

func (*SelfConfig) LocalStatus

func (s *SelfConfig) LocalStatus(ctx context.Context) (SelfConfigRecoveryStatus, error)

func (*SelfConfig) PreviewAdoption

func (s *SelfConfig) PreviewAdoption(ctx context.Context, actor Actor) (SelfConfigAdoptionPreview, error)

PreviewAdoption returns names only. Neither secret values nor unkeyed fingerprints reach the browser, and an existing binding forbids re-import.

func (*SelfConfig) ReconcileRuntime

func (s *SelfConfig) ReconcileRuntime(ctx context.Context) error

func (*SelfConfig) RecordRepairOrigin

func (s *SelfConfig) RecordRepairOrigin(ctx context.Context, origin string) error

RecordRepairOrigin records the RP of a validated, app-owned repair graph for an unconfigured joining node. It grants no active bundle or acknowledgement. A network caller cannot replace this evidence with a claimed request origin.

func (*SelfConfig) Recover

func (s *SelfConfig) Recover(ctx context.Context, revision int64) (SelfConfigRecoveryStatus, error)

Recover selects an exact uncollected published revision under host authority. The store refuses active writers and unresolved jobs. It preserves restored credential suspension, so choosing a revision cannot resume outbound mail.

func (*SelfConfig) ResolveRepairRuntimeBundle

func (s *SelfConfig) ResolveRepairRuntimeBundle(ctx context.Context) (*runtimeconfig.Bundle, error)

ResolveRepairRuntimeBundle supplies only the retained previous completed policy for a fenced boot repair graph. It grants no active-generation ack.

func (*SelfConfig) ResolveRuntimeBundle

func (s *SelfConfig) ResolveRuntimeBundle(ctx context.Context) (*runtimeconfig.Bundle, error)

ResolveRuntimeBundle resolves the authoritative startup configuration without acknowledging a node or installing application resources. The application calls it before constructing its service graph. A suspended binding still supplies its saved policy for the recovery UI; Capture remains fenced.

func (*SelfConfig) RestoreDeployment

func (s *SelfConfig) RestoreDeployment(ctx context.Context, actor Actor, req SelfConfigDeploymentRestoreRequest) (SelfConfigStatus, error)

RestoreDeployment authorizes only the retained external deployment rollback. The desired runtime target stays fenced until a separately authorized repair. One original job has one restore command; retries return that durable decision.

func (*SelfConfig) Run

func (s *SelfConfig) Run(ctx context.Context)

Run reconciles committed targets independently of the initiating request's lifetime or its actor's later grant changes. Its context must be app-owned.

func (*SelfConfig) Status

func (s *SelfConfig) Status(ctx context.Context, actor Actor) (SelfConfigStatus, error)

func (*SelfConfig) TestMail

type SelfConfigAdoptRequest

type SelfConfigAdoptRequest struct{ PreviewToken, IdempotencyKey string }

type SelfConfigAdoptionPreview

type SelfConfigAdoptionPreview struct {
	OwnerInstanceID          string
	SchemaVersion            int
	ConfiguredKeys, Warnings []string
	PreviewToken             string
}

type SelfConfigApplyRequest

type SelfConfigApplyRequest struct {
	Revision, ExpectedGeneration int64
	SchemaVersion                int
	IdempotencyKey               string
	ConfirmRestoredCredentials   bool
	PrepareOnly                  bool
	PlanDigest                   string
}

type SelfConfigBindingView

type SelfConfigBindingView struct {
	OrgID, ProjectID, EnvironmentID string
	SchemaVersion                   int
}

type SelfConfigDeploymentRestoreRequest

type SelfConfigDeploymentRestoreRequest struct {
	Revision, ExpectedGeneration int64
	SchemaVersion                int
	PlanDigest                   string
}

type SelfConfigJobView

type SelfConfigJobView struct {
	ID, State                                    string
	Revision, Generation                         int64
	CreatedAt                                    time.Time
	CompletedAt                                  *time.Time
	Error                                        string
	PlanDigest                                   string
	Prepared                                     bool
	DeploymentRestorePending, DeploymentRestored bool
}

type SelfConfigMailTestRequest

type SelfConfigMailTestRequest struct {
	Revision, ExpectedGeneration int64
	SchemaVersion                int
	To                           string
}

type SelfConfigMailTestResult

type SelfConfigMailTestResult struct {
	Revision int64
	Sent     bool
}

type SelfConfigNodeView

type SelfConfigNodeView struct {
	NodeID           string
	ActiveGeneration int64
	ActiveRevision   *int64
	State            string
	UpdatedAt        time.Time
	Error            string
}

type SelfConfigReauthTarget

type SelfConfigReauthTarget struct {
	Action                     string `json:"action"`
	OwnerInstanceID            string `json:"owner_instance_id"`
	Revision                   int64  `json:"revision"`
	SchemaVersion              int    `json:"schema_version"`
	ExpectedGeneration         int64  `json:"expected_generation"`
	PreviewToken               string `json:"preview_token"`
	To                         string `json:"to"`
	ConfirmRestoredCredentials bool   `json:"confirm_restored_credentials"`
	PlanDigest                 string `json:"plan_digest,omitempty"`
}

SelfConfigReauthTarget is an exact administrative decision, never a disclosure window. Empty fields are canonical and required so no omitted field broadens it.

type SelfConfigRecoveryStatus

type SelfConfigRecoveryStatus struct {
	OwnerInstanceID string `json:"owner_instance_id"`
	Managed         bool   `json:"managed"`
	Generation      int64  `json:"generation"`
	DesiredRevision int64  `json:"desired_revision"`
	Suspended       bool   `json:"suspended"`
}

SelfConfigRecoveryStatus contains only host-local operational metadata.

type SelfConfigStatus

type SelfConfigStatus struct {
	OwnerInstanceID                 string
	Managed                         bool
	Binding                         *SelfConfigBindingView
	Generation                      int64
	DesiredRevision, LatestRevision *int64
	State                           string
	Nodes                           []SelfConfigNodeView
	Job                             *SelfConfigJobView
}

type ServiceAccountView

type ServiceAccountView struct {
	ID        string
	Principal domain.PrincipalID
	Name      string
	Kind      domain.PrincipalClass
	CreatedAt time.Time
	CreatedBy domain.PrincipalID
	// LiveCredentials is how many of its credentials currently authenticate,
	// so an operator can see at a glance which accounts are actually in use.
	LiveCredentials int64
}

ServiceAccountView is the metadata surface of one service account.

type SessionCompletion

type SessionCompletion interface {
	// contains filtered or unexported methods
}

SessionCompletion is the closed input to the transaction-local session completion module. Creation and rotation are separate variants: creation owns a new row and clocks, while rotation preserves the live row's identity and clocks. A caller cannot select one behaviour with a Boolean flag.

type SessionView

type SessionView struct {
	ID                string
	Artifact          string
	AuthMethod        string
	CreatedAt         time.Time
	LastSeenAt        time.Time
	IdleExpiresAt     time.Time
	AbsoluteExpiresAt time.Time
	SourceIP          string
	UserAgent         string
	// RequestingOrigin is set for workspace sessions only. It is the field
	// that makes "which foreign shell is holding a session on my account"
	// answerable at a glance.
	RequestingOrigin string
	HandoffID        string
}

SessionView is one row of the caller's own active-session list. A workspace session appears here AS ITS OWN ARTIFACT TYPE — that is the ADR's requirement, and it is why the workspace session is a `sessions` row at all.

type SetPinRequest

type SetPinRequest struct {
	WorkloadPrincipalID domain.PrincipalID
	Revision            int64
	ExpiresAt           time.Time
	OverrideSchema      bool
}

type SetPinResult

type SetPinResult struct {
	Action PinAction
	Pin    PinView
}

type SignupDoor

type SignupDoor struct {
	Open    bool
	Paused  bool
	Methods []SignupMethod
	// Landing is the open door's landing kind (#607), for the confirmation
	// step; empty unless Open.
	Landing LandingKind
}

SignupDoor is the public sign-up door of one scope (`/auth/methods`). Closed (no policy, or an unknown org) and paused (a policy that is inactive) are both not open; paused is the one fact the public page may show ("Sign-up is paused.", #587 d3). The cause never leaves the Members panel.

type SignupMethod

type SignupMethod struct {
	Kind SignupMethodKind
	Slug string
}

SignupMethod is one way the door admits: a federated provider by {kind, slug}, or the local entry (Kind local, no slug).

type SignupMethodKind

type SignupMethodKind string

SignupMethodKind is one way an open door admits: a federated provider kind or the local entry.

const (
	SignupMethodOIDC   SignupMethodKind = SignupMethodKind(domain.ProviderOIDC)
	SignupMethodOAuth2 SignupMethodKind = SignupMethodKind(domain.ProviderOAuth2)
	SignupMethodLocal  SignupMethodKind = "local"
)

type SignupVerification

type SignupVerification struct{ Token, DisplayName, Password, OrgName, Landing string }

SignupVerification contains form fields. Email and identity come only from the token row.

type SnapshotKey

type SnapshotKey struct {
	KeyID          string
	Name           string
	Classification string
	Sensitive      bool
}

SnapshotKey is one delivered key of one snapshot, without its value. The value lives behind ExportWithParameters and its formula; a browse verb never emits one.

type StagedChange

type StagedChange struct {
	// VersionID is the immutable version id a selective publish names.
	VersionID          string
	KeyID              string
	Name               string
	Classification     string
	Operation          string
	StagedFromRevision int64
	CreatedAt          time.Time
	// Findings are the secret-scanning warnings this save produced (#74,
	// Surface 1). The save SUCCEEDS regardless; each finding names its rule and
	// key locator and carries a keep-as-config acknowledgement token. Empty on a
	// clean save, an unscanned (secret) key, or an Unset.
	Findings []Finding
}

StagedChange is one draft as reported to its owner.

type Status

type Status struct {
	State   authz.RestoreState
	Pending []authz.PrincipalRef
}

Status is what `hikyo restore status` prints: the posture plus who is still inert. Listing the outstanding set is not accepting it — the operator has to know who is waiting in order to reconcile them one at a time.

type System

type System struct {
	DB    *store.DB
	Store store.Config
}

System answers operational questions for the HTTP layer.

func (*System) Ready

func (s *System) Ready(ctx context.Context) error

Ready verifies this process still owns runtime admission in a read-only transaction. Missing/corrupt state, maintenance or stale identity refuse; readiness never creates migration bookkeeping or performs schema writes.

func (*System) RuntimeStatus

func (s *System) RuntimeStatus(ctx context.Context) (RuntimeStatus, error)

type TOTPStatusResult

type TOTPStatusResult struct {
	HasPassword   bool
	HasPasskey    bool
	CanReauthOIDC bool
	Establish     *CredentialEstablishStatus
	Confirmed     bool
	Pending       bool
}

TOTPStatusResult is the caller's current local credential inventory, pending TOTP enrollment and any unused session-bound establishment proof.

type TargetMutationMoveStarted

type TargetMutationMoveStarted struct {
	Move store.AdapterRouteMoveResult
}

type TargetMutationResult

type TargetMutationResult interface {
	// contains filtered or unexported methods
}

TargetMutationResult is the closed result of applying target intent. Its unexported marker keeps callers from inventing a third transport workflow.

type TargetMutationUpdated

type TargetMutationUpdated struct {
	Target store.AdapterTarget
}

type TokenKeyRotation

type TokenKeyRotation struct {
	// Version is the root token key's new version. It is operator-facing
	// bookkeeping only: the change token's public contract carries the SCHEME
	// version (`v1:`), never the key version, because a consumer that could
	// tell key versions apart could tell a rotation from a content change.
	Version uint32
}

TokenKeyRotation is one `rotate-token-key`.

type Transit

type Transit struct {
	DB      *store.DB
	Keyring *crypto.Keyring
	Custody *transit.Registry
	Budget  *Budget
	// Shared, when set (multi-node HA), charges the data-plane rate against
	// the installation-wide admission counters instead of this node's budget.
	Shared TransitWindowCounter
	Now    func() time.Time
}

Transit is the transit surface (#156, transit ADR): environment-scoped named keys whose material the caller never holds. Key management rides crypto-manage; the data plane rides crypto-use and is then narrowed by the key's own policy (state, version window, compromise, allowed operations and per-key caller entries), read inside the operation's own transaction.

Nothing about a key is cached between requests: every operation re-reads the key row (under a shared row lock on postgres), so a disable, compromise or deletion on any node binds the next request on every node.

func (*Transit) ChangeKeyState

func (s *Transit) ChangeKeyState(ctx context.Context, actor Actor, scope domain.Scope, name, action string, delay time.Duration) (TransitKeyView, error)

ChangeKeyState applies one lifecycle action (ADR D6). delay applies to schedule-deletion only; zero means seven days, and the accepted range is 24 hours through 90 days. Canceling deletion leaves the key disabled and is refused once the deadline has elapsed or purging has started. Compromise marks all current versions without changing state. Validation, authorization, and store errors propagate; a later view-read failure does not undo the change.

func (*Transit) ConfigureKey

func (s *Transit) ConfigureKey(ctx context.Context, actor Actor, scope domain.Scope, name string, req ConfigureTransitKeyRequest) (TransitKeyView, error)

ConfigureKey changes a key's version window, rotation period and caller entries (ADR D5, D7). Nil fields are unchanged; a present empty caller list clears restrictions, and a zero rotation period disables automatic rotation. Invalid version bounds or periods are refused. Authorization and store errors propagate; the update remains committed if reading the resulting view fails.

func (*Transit) CreateKey

func (s *Transit) CreateKey(ctx context.Context, actor Actor, scope domain.Scope, req CreateTransitKeyRequest) (TransitKeyView, error)

CreateKey creates a named key with its first version (ADR D1-D3). Empty custody defaults to software; an empty allowed-operation list enables the algorithm's operations except datakey-plaintext. Invalid configuration, duplicate names, and the environment key limit return errors. Authorization, custody, and transaction failures propagate; uncommitted external material is destroyed on a best-effort basis.

func (*Transit) DataKey

func (s *Transit) DataKey(ctx context.Context, actor Actor, scope domain.Scope, name string, bits int, aad []byte, reveal bool) (TransitOutput, error)

DataKey draws a fresh data key and returns it wrapped under the key, plus the plaintext when reveal is set and the key allows datakey-plaintext (ADR D4). The plaintext is display-once and the caller must zero it. bits may be 128, 256, or 512; zero defaults to 256. aad is caller context bound to the wrapped value. Input, policy, randomness, custody, and transaction errors propagate; any returned plaintext is zeroed on error.

func (*Transit) Decrypt

func (s *Transit) Decrypt(ctx context.Context, actor Actor, scope domain.Scope, name, ciphertext string, aad []byte) (TransitOutput, error)

Decrypt opens a ciphertext (ADR D4). The plaintext is display-once: Hikyo neither stores nor logs it. aad must match the encryption context. Malformed ciphertext and authentication failures become invalid-input errors; key-policy, custody, and transaction errors propagate. The caller must zero returned Plaintext; on error this method zeroes it and returns an empty result.

func (*Transit) Encrypt

func (s *Transit) Encrypt(ctx context.Context, actor Actor, scope domain.Scope, name string, plaintext, aad []byte, keyVersion uint32) (TransitOutput, error)

Encrypt seals plaintext under the key (ADR D4). keyVersion 0 means latest. aad is caller context bound to the ciphertext; plaintext and context are limited to MaxTransitPlaintextBytes and MaxTransitContextBytes. Value holds the versioned ciphertext. Input, key-policy, custody, and transaction errors propagate; use the output only when err is nil.

func (*Transit) GetKey

func (s *Transit) GetKey(ctx context.Context, actor Actor, scope domain.Scope, name string) (TransitKeyView, error)

GetKey returns one key's metadata, versions and caller entries. Missing or destroyed keys return a not-found error; address, authorization, and store errors propagate.

func (*Transit) HMAC

func (s *Transit) HMAC(ctx context.Context, actor Actor, scope domain.Scope, name string, message []byte, keyVersion uint32) (TransitOutput, error)

HMAC computes a MAC with the key (ADR D4). keyVersion 0 means latest.

func (*Transit) ListKeys

func (s *Transit) ListKeys(ctx context.Context, actor Actor, scope domain.Scope) ([]TransitKeyView, error)

ListKeys lists an environment's non-destroyed keys by name (metadata only), including versions, callers, and rotation status. Scope, authorization, and store errors propagate.

func (*Transit) PurgeDue

func (s *Transit) PurgeDue(ctx context.Context) (destroyed int, err error)

PurgeDue destroys every key whose deletion delay has elapsed (ADR D6): external material is destroyed at its provider first, then every version's material is erased and the key tombstoned in one transaction. An unavailable external provider leaves the key pending-deletion (unusable either way) for the next run. It returns the successful purge count and joined per-key errors. A page-read failure stops the sweep and joins that error with earlier failures; completed purges remain committed.

func (*Transit) Rewrap

func (s *Transit) Rewrap(ctx context.Context, actor Actor, scope domain.Scope, name, ciphertext string, aad []byte) (TransitOutput, error)

Rewrap moves a ciphertext onto the key's latest producing version without returning the plaintext (ADR D5). The audit record names the new version.

func (*Transit) RotateDue

func (s *Transit) RotateDue(ctx context.Context) (rotated int, err error)

RotateDue appends a version to every active key whose rotation period has elapsed since its latest version (ADR D5). It runs under scheduler authority and records a rotation event with actor class system. Unavailable custody leaves the current version unchanged for a later sweep to retry. It returns the successful rotation count and joined per-key errors. A page-read failure stops the sweep and joins that error with earlier failures; completed rotations remain committed.

func (*Transit) RotateKey

func (s *Transit) RotateKey(ctx context.Context, actor Actor, scope domain.Scope, name string) (TransitKeyView, error)

RotateKey appends a new version (ADR D5), including for retired or disabled keys. Pending deletion is refused; concurrent rotation and the retained-version limit return conflict and limit errors. Authorization, custody, and store errors propagate. Rotation remains committed if reading the updated view fails.

func (*Transit) Sign

func (s *Transit) Sign(ctx context.Context, actor Actor, scope domain.Scope, name string, message []byte, keyVersion uint32) (TransitOutput, error)

Sign signs message with the key (ADR D4). keyVersion 0 means latest.

func (*Transit) TrimKey

func (s *Transit) TrimKey(ctx context.Context, actor Actor, scope domain.Scope, name string) (TransitKeyView, int64, error)

TrimKey permanently deletes versions below min_decrypt_version (ADR D5). It first fences the trim: the key's trim floor (min_available_version) is raised to min_decrypt_version, after which ConfigureKey can no longer lower min_decrypt_version past it. External custody then destroys the material below the floor at the provider; an unavailable provider refuses the trim rather than leaving material orphaned. Retries can finish external destruction before the version rows below the floor are deleted. It returns the updated view and deleted row count. The floor and any external destruction persist on later failure; deletion stays committed if reading the view fails. Authorization, custody, and store errors propagate.

func (*Transit) Verify

func (s *Transit) Verify(ctx context.Context, actor Actor, scope domain.Scope, name string, message []byte, signature string) (TransitOutput, error)

Verify checks a signature locally against the version's stored public key, after checking custody availability; no private operation is requested. A well-formed transit value with a mismatched signature returns Valid=false. Malformed values or oversized inputs return invalid-input errors; unavailable or compromised versions are refused. Authorization, budget, and store errors propagate; use the output only when err is nil.

func (*Transit) VerifyHMAC

func (s *Transit) VerifyHMAC(ctx context.Context, actor Actor, scope domain.Scope, name string, message []byte, mac string) (TransitOutput, error)

VerifyHMAC recomputes the MAC and compares in constant time. A mismatch is a successful operation answering Valid=false. Malformed transit values or oversized inputs return invalid-input errors; unavailable or compromised versions are refused. Authorization, budget, custody, and store errors propagate; use the output only when err is nil.

type TransitCallerEntry

type TransitCallerEntry struct {
	PrincipalID string
	Operations  []string
}

TransitCallerEntry is one per-key caller entry on the request and view side.

type TransitKeyView

type TransitKeyView struct {
	store.TransitKeyRecord
	Versions    []store.TransitVersionRecord
	Callers     []store.TransitCaller
	RotationDue bool
}

TransitKeyView is a key's metadata: never material, never a data-plane output.

type TransitOutput

type TransitOutput struct {
	KeyVersion uint32
	Value      string
	Plaintext  []byte
	Valid      bool
}

TransitOutput is a data-plane result. Value is the caller-facing ciphertext, signature or MAC; Plaintext is set only by decrypt and datakey-plaintext and is display-once. Valid is set by the two verify operations.

type TransitWindowCounter

type TransitWindowCounter interface {
	BumpWindow(ctx context.Context, bucket, subject string, window time.Time) (int64, error)
}

TransitWindowCounter is the slice of the #146 shared admission store the transit rate limit needs. *store.Coordination satisfies it.

type UnheldGrantReach

type UnheldGrantReach struct {
	Instance bool
	Orgs     []domain.OrgID
}

UnheldGrantReach is where the grant-unheld rule lets a grantor hand out a capability it does not hold: every organisation under an instance-scope `manage-members`, else the organisations it holds that atom at org scope.

type UpdateAdapterTargetRequest

type UpdateAdapterTargetRequest struct {
	Flags              *AdapterTargetFlagPatch
	TargetID           string
	ExpectedGeneration int64
	Target             AdapterTargetInput
}

type Updates

type Updates struct {
	SelfConfig *SelfConfig
	DB         *store.DB
	Source     updatecheck.Source
	Version    string
	Channel    updatecheck.Channel
	Control    updater.Control
	Now        func() time.Time
	Log        *slog.Logger
	// contains filtered or unexported fields
}

Updates owns the authenticated release-notification read. No database transaction remains open across the bounded public release lookup.

func (*Updates) GetJob

func (s *Updates) GetJob(ctx context.Context, actor Actor, id string) (updater.Job, error)

GetJob reads helper-owned durable state. The first terminal observation appends the correlated outcome before acknowledging it to the helper.

func (*Updates) GetStatus

func (s *Updates) GetStatus(ctx context.Context, actor Actor) (updatecheck.Status, error)

GetStatus authorizes an instance-config read, selects the newest admitted release, then re-authorizes and records the successful answer atomically.

func (*Updates) ReconcileOutcomes

func (s *Updates) ReconcileOutcomes(ctx context.Context) error

func (*Updates) Request

func (s *Updates) Request(ctx context.Context, actor Actor, version string) (updater.Job, error)

Request preserves authenticated refusal evidence but cannot contact the retired deployment helper. Release discovery remains independently available.

func (*Updates) Run

func (s *Updates) Run(ctx context.Context)

Run reconciles helper-owned terminal outcomes independently of any browser. The helper journal is durable, so startup catches outcomes completed while the server was stopped; the short poll records ordinary completions promptly.

type UserPatchClearExternalID

type UserPatchClearExternalID struct{}

type UserPatchCommand

type UserPatchCommand interface {
	// contains filtered or unexported methods
}

UserPatchCommand is the closed set of user PATCH mutations. The private marker prevents transport or store packages from adding unhandled variants.

type UserPatchMergeAttributes

type UserPatchMergeAttributes struct{ Attributes map[string]any }

type UserPatchSetActive

type UserPatchSetActive struct{ Active bool }

type UserPatchSetExternalID

type UserPatchSetExternalID struct{ ExternalID string }

type UserPatchSetUserName

type UserPatchSetUserName struct{ UserName string }

type ValidatedChange

type ValidatedChange struct {
	KeyID          string
	Name           string
	Classification string
	Operation      string
	// Valid is false when publish would refuse this change today.
	Valid bool
	// Problems are the publish-time refusals, each in wire-safe wording.
	Problems []string
	// ValidationDeferred reports a config value that references environment
	// parameters: its final schema check runs at delivery with the caller's
	// parameters, so structural validity is all that can be reported here.
	ValidationDeferred bool
	// Findings are the secret-scanner matches over a config value. None
	// carries an acknowledgement: validate is a diagnostic, not an ingress.
	Findings []Finding
}

ValidatedChange is the verdict on one proposed change (mcp-write ADR § 1). It carries what publish would refuse, in the same safe wording publish uses. A schema failure on a config key may quote the offending fragment, as it does over REST; a secret key's engine text never carries instance data.

type ValueCell

type ValueCell struct {
	KeyID          string
	Name           string
	Classification string
	Set            bool
	Value          string
	Revealed       bool
	UpdatedAt      time.Time
	UpdatedBy      string
}

ValueCell is one `(key, environment)` cell as reported to a reader.

Presence is the single boolean `Set`. That is the whole presence model — there is no mode, no enum with a third member, and no "masked" anything. A cell that is not `Set` carries no value from any source, which is what "no fallback source exists" means once inheritance is gone.

Value carries plaintext ONLY where the reader was authorized to see it: `config` under `read`, `secret` under `read ∧ reveal`. Revealed says which happened, so a caller can tell "" (an empty value the operator set) from "" (a secret they may not read) without guessing.

type Values

type Values struct {
	DB      *store.DB
	Keyring *crypto.Keyring
	// Advisory receives the metadata-only staging events, AFTER commit. Nil
	// disables the channel; correctness never depends on delivery.
	Advisory *Advisory
	// Auth supplies the reveal guard (#58): every route in the formula table
	// that carries a `reveal` conjunct consumes this session's reauthentication
	// window over the environment it discloses in, for exactly the keys it
	// discloses. Nil is a wiring fault and refuses every disclosure loudly
	// (ErrNoCeremonySeam) rather than disclosing without a ceremony.
	Auth *Auth
	// Scan is the secret-scanning ruleset (#74). The Surface-1 config-value
	// ingresses (stage/declare/copy/clone/import) run it after authorization and
	// ride any findings on the response. Nil disables the scan (pre-#74 tests); a
	// booted server always wires it.
	Scan *scanning.Ruleset
	// Budget applies the §179 fail-closed default (60/min·principal, 8/org) to
	// the two bulk value fan-outs with no named category — Import and Copy. Nil
	// disables it.
	Budget *Budget
}

Values owns the value surface. Every method addresses an environment or the project that holds several of them.

The Keyring is here rather than in the store because the store never sees plaintext: this layer seals before writing and opens after reading, and the AAD it builds names exactly the row the ciphertext is allowed to live on.

func (*Values) Copy

func (s *Values) Copy(ctx context.Context, actor Actor, scope domain.Scope, req CopyRequest) (CopyResult, error)

Copy is copy-to and bulk-apply: server-side duplication of STORED material into one or more destinations. Every copy produces an INDEPENDENT value — the ciphertext is never carried over, the plaintext is re-sealed under the destination row's own AAD, and no ongoing relationship is created, so editing the source later changes nothing downstream.

The locked formula, split across the scopes and the classifications it names (see materialSet):

secret material: reveal(source) ∧ reveal(destination) ∧ publish(destination)
config material:   read(source) ∧                       publish(destination)

A named `secret` the caller cannot read out of the source REFUSES the copy. Only clone-at-creation tolerates a failed source gate, because only clone is specified to proceed with what it could take and enumerate the rest.

func (*Values) Declare

func (s *Values) Declare(ctx context.Context, actor Actor, scope domain.Scope, envIDs []string, keyName, value string) ([]ValueCell, []Finding, error)

Declare is declare-into-environments: ONE supplied plaintext into several environments in one transaction. It is the flat model's answer to "I don't want to type this 4 times", and it creates no relationship between the copies — each is an independent value, and editing one later changes nothing elsewhere, by design.

It is authorized per DESTINATION, exactly as a single write is: holding `edit ∧ publish` on two of three environments does not buy the third, and the whole call is refused rather than partially applied.

func (*Values) Diff

func (s *Values) Diff(ctx context.Context, actor Actor, scope domain.Scope, leftEnv, rightEnv string, reveal bool) ([]DiffRow, error)

Diff compares two environments on demand.

This is NOT the ambient drift signal the flat model deleted: divergence between environments is the point of the model, so equality is not a health signal and nothing watches it. This is an explicit, authorized, per- invocation comparison, under the oracle rules — write-presence without the reveal gate, plaintext only with it, and one disclosure event per key per side that was actually disclosed.

func (*Values) Get

func (s *Values) Get(ctx context.Context, actor Actor, scope domain.Scope, keyName string, reveal bool) (ValueCell, error)

Get reads one cell. reveal asks for `secret` plaintext and carries the locked disclosure formula plus one audit event; without it a `secret` cell reports write-presence only, and a `config` cell reports its value under plain `read` because classification IS the sensitivity boundary.

func (*Values) Import

func (s *Values) Import(ctx context.Context, actor Actor, scope domain.Scope, req ImportRequest) (ImportResult, error)

Import is phase 2: `values import` against one environment, in ONE transaction.

The order is load-bearing and is the ADR's own:

  1. authorize the import itself (`edit ∧ publish` on this environment);
  2. re-evaluate phase 1's read formula — read@project AND read@environment for the union of the manifest's environments AND this import's target — in the same transaction, on top of the verb's formula. A caller lacking it gets the plain authorization failure and no precondition result: the precondition is not an oracle, and the union is what keeps that true when the caller chooses the manifest's list;
  3. only then verify the occurrence tokens, per key.

Any movement rejects, naming the keys, and NOTHING is written: the whole run is one transaction, and a partially applied migration whose manifest no longer describes it is worse than one the human re-runs.

func (*Values) Initialize

func (s *Values) Initialize(ctx context.Context, actor Actor, scope domain.Scope, keyName, value string, acks []string) (StagedChange, error)

Initialize stages the first value under Define keys and Publish. It does not replace a published cell or another principal's pending work.

func (*Values) List

func (s *Values) List(ctx context.Context, actor Actor, scope domain.Scope, reveal bool) ([]ValueCell, error)

List reads the environment's whole resolved set: one row per DECLARED key, each `set` or `absent`. In the flat model this IS the resolution — a lookup per key with nothing underneath — so an absent row carries no value from anywhere, which is the property C2 asks to see.

func (*Values) ListPage

func (s *Values) ListPage(ctx context.Context, actor Actor, scope domain.Scope, afterName string, limit int) ([]ValueCell, error)

ListPage is the bounded keyset read behind hikyo_inspect_configuration. It pages the catalogue by the UNIQUE key name and resolves each page key's cell with a point read; reveal is always false, so `config` plaintext appears and a `secret` cell carries only its classification and set/absent presence.

func (*Values) Occurrences

func (s *Values) Occurrences(ctx context.Context, actor Actor, scope domain.Scope, candidates []ImportCandidate) (ImportPresence, error)

Occurrences is phase 1's read. Candidates are the key declarations the run intends to propose; every one gets a token, declared or not.

func (*Values) Set

func (s *Values) Set(ctx context.Context, actor Actor, scope domain.Scope, keyName, value string, acks []string) (StagedChange, error)

Set stages one edit into the caller's own working state.

IT PUBLISHES NOTHING. An edit to a `(key, environment)` is saved immediately as a pending change owned by the caller, recorded against the published revision it was staged from, and delivery does not move until a publish names its version id. The formula is therefore `edit` ALONE -- `edit` confers no delivery power, and edit-without-publish IS the propose-and-review flow the permission-model ADR says it is.

SAVING IS FREE. The value is not validated here and a `required_in` key may be cleared here: a draft is the user's scratchpad, and blocking a save pushes work in progress into external notepads, which for secrets is exactly where it must not go. Every one of those refusals lives at publish instead.

func (*Values) Unset

func (s *Values) Unset(ctx context.Context, actor Actor, scope domain.Scope, keyName string) (StagedChange, error)

Unset stages a clear: the cell goes to `absent` when the draft is published. It writes no value, so it never scans and takes no acknowledgements.

func (*Values) ValidateSet

func (s *Values) ValidateSet(ctx context.Context, actor Actor, scope domain.Scope, keyName, value string) (ValidatedChange, error)

ValidateSet evaluates staging `value` into `keyName` without staging it. It requires exactly the authority `Set` requires (`edit@env`) and is audited as an authority-bearing action; it mutates nothing else.

func (*Values) ValidateUnset

func (s *Values) ValidateUnset(ctx context.Context, actor Actor, scope domain.Scope, keyName string) (ValidatedChange, error)

ValidateUnset evaluates clearing `keyName` without staging the clear.

type WideningGain

type WideningGain struct {
	Principal  domain.PrincipalID
	Name       string
	Capability domain.Capability
	Envs       []domain.EnvID
}

WideningGain is one capability a person gains on the moved key, with the environments it newly reaches (empty for a project-wide atom only).

type Workspace

type Workspace struct {
	DB *store.DB

	// Version is this build's version string, served in the directory listing.
	// It is injected rather than read from internal/app because app imports
	// service; a display string is not worth an import cycle. Empty is
	// tolerated: the listing's version field is DISPLAY-ONLY and never feeds a
	// compatibility decision — the shell reads meta live for that.
	Version string
	// Reauth is the human-auth service, consulted for one thing only: the
	// per-environment reauthentication bounds a step-up elevation opens its
	// window under. It is the concrete service rather than an interface
	// because there is exactly one, and duplicating the effective-window
	// resolution here is how a lowered environment ends up honoured on one
	// path and not the other.
	Reauth *Auth
	Now    func() time.Time
	// contains filtered or unexported fields
}

Workspace is the serving side's service.

func (*Workspace) AddOrigin

func (s *Workspace) AddOrigin(ctx context.Context, actor Actor, origin string) (OriginView, error)

AddOrigin consents to one EXACT origin, and RETURNS the entry it wrote.

Returning it is not a convenience: the transport's 201 body needs the canonical origin and its provenance, and the only alternative — calling ListOrigins straight after — authorizes a second time and puts a spurious `remote.origin_allowlist_read` on the trail for an add nobody asked to read.

func (*Workspace) ApproveHandoff

func (s *Workspace) ApproveHandoff(ctx context.Context, actor Actor, state string) (code string, redirectURI string, err error)

ApproveHandoff binds the authenticated human and mints the authorization code. The human authenticated in the popup, on THIS instance's origin, with THIS instance's own ceremonies — which is why the actor here is an ordinary session of this instance and not anything the viewing side supplied.

The front channel receives code and state only. The artifact never crosses a redirect.

func (*Workspace) ListConnections

func (s *Workspace) ListConnections(ctx context.Context, actor Actor) ([]ConnectionView, error)

ListConnections is metadata only. It is audited rather than `audited: none` because reading which foreign installations may read this one's directory is not a bare tenant read — the audit-model ADR's default-deny refuses the permit.

func (*Workspace) ListOrigins

func (s *Workspace) ListOrigins(ctx context.Context, actor Actor) ([]OriginView, error)

ListOrigins is the consent list.

func (*Workspace) ListSessions

func (s *Workspace) ListSessions(ctx context.Context, actor Actor) ([]SessionView, error)

ListSessions is SELF-SCOPED: the caller's own sessions and nothing else. It needs no capability for the reason /api/v1/me/orgs needs none — it is a projection of what the caller already holds — and requiring one would make incident response depend on an authority an attacker may have just removed.

func (*Workspace) MintConnection

func (s *Workspace) MintConnection(ctx context.Context, actor Actor, label string, req MintRequest) (MintConnectionResult, error)

MintConnection creates the principal, its single credential and its single `instance-directory` grant AS ONE UNIT, in one transaction.

One credential per principal, ever. Rotation is a new create and a revoke of the predecessor, never a second credential on this row — which is why revoke retires the principal with the credential and no orphan can accumulate.

The grant is written at the STORE layer by this minter and not through the grants API, so the grants API's mintable-origin set is untouched. The class allowlist is what makes the grant safe: `instance-connection` may hold exactly `instance-directory` and nothing else, and the grants API refuses to attach that capability to a machine principal by hand.

func (*Workspace) OriginAllowed

func (s *Workspace) OriginAllowed(ctx context.Context, origin string) (bool, error)

OriginAllowed is the pre-authentication membership check CORS and handoff issuance both consult. It runs in its own read transaction and takes no actor: it is consulted BEFORE anyone is authenticated, which is the whole point of an allowlist.

func (*Workspace) PrimeOriginAllowlist

func (s *Workspace) PrimeOriginAllowlist(ctx context.Context) error

PrimeOriginAllowlist loads the request-path snapshot before the public listener serves. A load error is a boot refusal: silently starting with an empty snapshot would turn configured cross-origin consent into a denial.

func (*Workspace) RedeemHandoff

func (s *Workspace) RedeemHandoff(ctx context.Context, code, pkceVerifier, origin string) (WorkspaceSession, error)

RedeemHandoff exchanges code + PKCE verifier for a workspace session.

The session row is a `sessions` row in every locked mechanical respect — fast-hash verifier, artifact type, generation binding, credential epoch, idle and absolute clocks — differing only in transport and in its two bound extras. That is not a shortcut: it is what makes explicit revocation, grant-change invalidation, generation bumps, account disablement and restore inertness apply to a workspace session for free and structurally.

The CSRF verifier is nil, like a CLI session's: the bearer rides an Authorization header, nothing is ambient, and demanding a synchronizer token on a non-cookie transport would be theatre.

func (*Workspace) RemoveOrigin

func (s *Workspace) RemoveOrigin(ctx context.Context, actor Actor, origin string) (int64, error)

RemoveOrigin is the KILL SWITCH. Removing the entry and revoking every workspace session bound to it happen in ONE transaction, which is what makes de-allowlisting a real kill switch rather than a headers change: there is no window in which the origin is de-allowlisted and its sessions still authenticate.

func (*Workspace) RevokeConnection

func (s *Workspace) RevokeConnection(ctx context.Context, actor Actor, id string) error

RevokeConnection kills the credential and retires the principal with it. It bites at the NEXT presentation: the liveness predicate is read in the authenticating transaction, uncached, so there is no window in which a revoked connection still serves a listing.

func (*Workspace) RevokeSession

func (s *Workspace) RevokeSession(ctx context.Context, actor Actor, id string) error

RevokeSession kills one of the caller's OWN sessions, and it bites mid-flight because the next request re-resolves the row in its own transaction.

The principal conjunct lives in the SQL, not in a Go check: one caller is structurally unable to reach another's row by guessing an id.

func (*Workspace) Serve

func (s *Workspace) Serve(ctx context.Context, actor Actor) (remotefetch.Listing, error)

Serve builds the authenticated directory listing.

What the connection credential authorizes, exhaustively: instance identity, version, and the NAMES and counts of orgs and projects. No values, no keys, no environments, no membership, no settings, no audit — and there is no field on remotefetch.Listing that could carry one.

The listing is an INSTANCE-SCOPE READ CROSSING ORG BOUNDARIES BY DESIGN, which is why it is its own registered operation served under an InstanceProof rather than a tenant read repeated per org. Project names come from ONE instance-scoped query: looping per org would mint N tenant proofs for one operation and misreport it in the boundary check.

func (*Workspace) ShowConnection

func (s *Workspace) ShowConnection(ctx context.Context, actor Actor, id string) (ConnectionView, error)

ShowConnection is one connection's metadata.

func (*Workspace) ShowHandoff

func (s *Workspace) ShowHandoff(ctx context.Context, actor Actor, state string) (HandoffView, error)

ShowHandoff returns the purpose and any step-up policy a live transaction binds, so the approve page chooses the ceremony and names its exact scope from the server-owned row rather than trusting URL parameters. The key set can be large, and a URL is the wrong place for the authoritative binding to live.

It READS, it does not consume, and it answers only the authenticated human on this instance (the approve page always has that session for a step-up). What it returns are identifiers; a stolen state would leak env and key ids, never values, and only for the transaction's few live minutes.

func (*Workspace) StartHandoff

func (s *Workspace) StartHandoff(ctx context.Context, req HandoffRequest) (HandoffStart, error)

StartHandoff opens a single-use transaction bound to an allowlisted origin.

It is PRE-AUTHENTICATION: no session exists yet for an establishment, and the step-up case authenticates inside the popup on this instance's own origin. The allowlist is the gate, and it is checked here rather than only at CORS because CORS binds browsers, not tokens.

type WorkspaceSession

type WorkspaceSession struct {
	Value             string
	SessionID         string
	Origin            string
	HandoffID         string
	IdleExpiresAt     time.Time
	AbsoluteExpiresAt time.Time
	// Elevated is set when this redemption ELEVATED the session it was bound to
	// rather than establishing a new one. The id is the same session's; the
	// value is that same session's rotated bearer, not a second one.
	Elevated bool
	// EnvironmentID and WindowExpiresAt describe the reauthentication window the
	// elevation opened. Both are empty on an establishment.
	EnvironmentID   string
	WindowExpiresAt time.Time
}

WorkspaceSession is a redeemed workspace bearer. The value is returned once and lives in the shell's JS MEMORY ONLY — never a cookie, never localStorage or sessionStorage, gone on tab close.

Source Files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL