hikyo

module

v0.0.1-nightly.2026083... Latest Latest Go to latest Published: Aug 30, 2026 License: MPL-2.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/Hikyo-Org/hikyo

Links

Open Source Insights

README ¶

Hikyo

Secrets and configuration you can reason about.

A fully open-source, self-hosted control plane for explicit values across development, staging, and production.

Documentation · Getting started · Self-hosting · Contributing

[!IMPORTANT] Release maturity, interface freeze, and distribution status live only under CAP-PUBLIC-RELEASE in the machine-checked implementation-status ledger.

Implementation status

Show fully implemented, partially implemented, and open features

“Implemented” means the feature and its acceptance evidence are present in the repository. The machine-checked implementation-status ledger is the only current-status authority; ADRs/specs define obligations and handoffs remain immutable evidence.

Fully implemented

Feature	Included
`CAP-RUNTIME-STORAGE` Runtime and storage	Single multicall binary, SQLite and PostgreSQL stores, migrations, and CI
`CAP-SECURITY-FOUNDATIONS` Security foundations	Envelope encryption, authorization chokepoint, append-only audit trails, and gap-free PostgreSQL audit export
`CAP-CORE-API-CLI` Core API and CLI	Bootstrap administration, local login, hierarchy CRUD, key declarations, validation, encrypted values, copy, clone, and bulk apply
`CAP-HUMAN-ACCESS` Human identity and access	OIDC, WebAuthn, TOTP, recovery, sessions, grants, role templates, and protected environments
`CAP-MATRIX-DISCLOSURE` Matrix and disclosure UI	Embedded app shell, environment matrix, row editor, problems filter, reveal/copy ceremonies, and protected publish flows
`CAP-MACHINE-ACCESS` Machine access	Service accounts, display-once credentials, OIDC workload federation, and machine-access UI
`CAP-MULTI-INSTANCE` Multi-instance workspaces	Directory-tier remotes and browser-direct workspace sessions
`CAP-ENTERPRISE-IDENTITY` Enterprise identity protocols	SAML service-provider support and SCIM provisioning, fully open-source
`CAP-BACKUP-RESTORE` Backup and restore	Encrypted export/restore plus the cross-engine recovery drill
`CAP-REVISION-LIFECYCLE` Revision lifecycle	Drafts, snapshots, selective publish, rollback, durable pins, retention, GC, and history restore/pin lifecycle
`CAP-ADMINISTRATION-UI` Administration UI	Members, organisation/project settings, account security, instance administration, and browser step-up
`CAP-IMPORTS-ONBOARDING` Imports and onboarding	Kubernetes, SOPS, and Infisical file imports; live Kubernetes and Vault/OpenBao connectors; import wizard; dotenv scaffolding
`CAP-DELIVERY` Delivery	Compose delivery and `hikyo run`, Kubernetes operator/CRDs, Forgejo and GitHub Actions adapters, and machine-reveal opt-in
`CAP-KEY-ROTATION` Key rotation	Root, master, DEK, token, and scanning-key rotation plus resumable re-encryption
`CAP-SECRET-SCANNING` Secret scanning	Surface-1 warnings and Surface-2 blocks on every CLI/API value ingress
`CAP-SUPPLY-CHAIN-SITE` Supply chain and project site	Signed release pipeline, SBOMs, documentation/governance site, matching icons, and offline-capable PWA

Partially implemented

Feature	What works now	Needed for complete implementation
`CAP-PRODUCTION-OPS` Production operations	All registered operational bounds, doctor, upgrade path, no-egress posture, and pinned operator resource limits	Record an arm64 cgroup run proving operator reconciliation within the 128 MiB limit under load
`CAP-PUBLIC-RELEASE` Public release and distribution	Cosign trust, SBOM generation, GoReleaser/Helm packaging, and installer verification	Run full acceptance, freeze API/CLI, and publish 1.0 under #79
`CAP-BROWSER-SCANNING` Secret scanning in the browser	CLI/API Surface-1 warnings and Surface-2 blocks	SPA block dialog after declaration editing lands under #183

One matrix. No hidden inheritance.

Hikyo makes every environment answer for itself. A value is explicitly set or absent; production never silently borrows a development default.

Key	development	staging	production
`DATABASE_URL`	● secret set	● secret set	● secret set
`LOG_LEVEL`	`debug`	`info`	`info`
`SENTRY_DSN`	○ absent	● secret set	● secret set

The same model is available through the embedded web UI, CLI, and API. Hikyo ships as one Go binary and supports both SQLite and PostgreSQL.

What makes Hikyo different

Explicit state. Empty never means “inherited,” “unknown,” or “use a default.” Each environment records set or absent.
Declarations before values. Define config vs. secret, validation, and presence rules first. Invalid writes are refused before state changes.
Deliberate secret disclosure. Normal reads return metadata and presence. Reveal and copy require reauthentication and create dedicated audit events.
One authorization chokepoint. Humans, machine identities, and local break-glass use the same capability-and-scope decision model.
Self-hosting is the product. One binary, an embedded UI, your database, your root key, and no enterprise-only implementation.

Quick start

Requires Go 1.27+, Node.js 26.7.0 (see .nvmrc), Corepack 0.35.0, and pnpm 11.24.0.

git clone https://github.com/Hikyo-Org/Hikyo.git
cd Hikyo

npm install --global --ignore-scripts corepack@0.35.0
corepack enable
corepack install --global pnpm@11.24.0
pnpm --dir clients/ts install --frozen-lockfile
pnpm --dir web install --frozen-lockfile
pnpm --dir web build
go build -tags ui -o ./bin/hikyo ./cmd/hikyo

./bin/hikyo server --dev

Open http://127.0.0.1:8080. The command creates hikyo-dev.db and a permission-0600 root key in the current directory.

--dev is loopback-only and intended for evaluation. A -tags ui build embeds the browser app; a plain go build produces an API-only binary.

Next, follow Getting started to create the first administrator, then Your first project to declare a key and set its first value.

CLI at a glance

One binary handles both operator and day-to-day client workflows.

# Operate the instance
hikyo server [--dev] [--listen ADDR] [--root-key-file PATH]
hikyo migrate
hikyo admin create --username admin
hikyo backup export
hikyo restore run --from <archive> --identity-file <path>
hikyo update channel stable|nightly|off
hikyo update check

# Create a scoped environment
hikyo login <instance-url> --local --as <user>
hikyo org create --name <name>
hikyo project create --name <name> --org <org-id>
hikyo env create --name <name> --org <org-id> --project <project-id>
hikyo context create <name> --instance <url> --org <id> --project <id> --env <id>

# Declare and manage values
hikyo key create --context <ctx> --name NAME --classification config|secret \
  --declaration '{"rule":{"type":"string"}}'
hikyo values set NAME --context <ctx> --value-file PATH
hikyo values get NAME --context <ctx>
hikyo values get NAME --context <ctx> --reveal --output-file PATH
hikyo values list --context <ctx>
hikyo values diff --context <ctx> --left development --right production
hikyo values copy --context <ctx> --from staging --to production --keys NAME

Secret values never belong in command-line arguments. Use --value-file or --stdin. See the complete CLI reference.

Run in production

Outside --dev, provide a datastore, native TLS certificate, external origin, and root key:

HIKYO_DB=sqlite:/var/lib/hikyo/hikyo.db \
HIKYO_EXTERNAL_ORIGIN=https://hikyo.example.com \
./hikyo server --listen 0.0.0.0:8443 \
  --operational-listen 127.0.0.1:8081 \
  --tls-cert-file /etc/hikyo/tls.crt \
  --tls-key-file /etc/hikyo/tls.key \
  --root-key-file /etc/hikyo/root.key

HIKYO_DB accepts sqlite:PATH or a PostgreSQL DSN. Native TLS reloads renewed files without restart. Reverse-proxy mode remains available when exact trusted proxy CIDRs are configured; never expose that plaintext listener directly.

Read Self-hosting before deployment and Configuration for every flag and environment variable.

Fully open. One product.

Every capability required to run Hikyo in production is and will remain open source; there is no /ee directory and there will never be one.

The enforceable commitment and amendment process live in GOVERNANCE.md.

Explore the project

Goal	Start here
Learn the model	Core concepts
Build from source	Installation
Operate an instance	Self-hosting
Use the terminal	CLI reference
Contribute code	Contributing guide
Read the design decisions	Architecture decision records and specification set

Security · Support · Governance · Trademark

License

Hikyo is licensed under the Mozilla Public License 2.0.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
api Package api is the HTTP contract.	Package api is the HTTP contract.
apigen Package apigen provides primitives to interact with the openapi HTTP API.	Package apigen provides primitives to interact with the openapi HTTP API.
cmd
bench-scan command Command bench-scan measures the secret scanner against the fixture corpus: per-item latency distribution (p50/p99) at the 64 KiB size cap, boot-compile (Load) duration, and peak RSS where cheaply obtainable.	Command bench-scan measures the secret scanner against the fixture corpus: per-item latency distribution (p50/p99) at the 64 KiB size cap, boot-compile (Load) duration, and peak RSS where cheaply obtainable.
hikyo command hikyo is the multicall binary: `hikyo server` and `hikyo migrate` are real; client verbs are stubs until their tickets land.	hikyo is the multicall binary: `hikyo server` and `hikyo migrate` are real; client verbs are stubs until their tickets land.
internal
adapter Package adapter defines the compiled-in deployment-module seam.	Package adapter defines the compiled-in deployment-module seam.
adapter/forgejo Package forgejo is the Forgejo REST v1 reference deployment adapter.	Package forgejo is the Forgejo REST v1 reference deployment adapter.
adapter/githubactions Package githubactions implements the GitHub Actions deployment adapter.	Package githubactions implements the GitHub Actions deployment adapter.
admission Package admission is the pre-authentication admission control the threat model requires and the ops spec dimensions: an instance-wide semaphore over Argon2id execution, a bounded queue, per-source-IP rate limiting, and per-account backoff.	Package admission is the pre-authentication admission control the threat model requires and the ops spec dimensions: an instance-wide semaphore over Argon2id execution, a bounded queue, per-source-IP rate limiting, and per-account backoff.
app Package app wires config, store, migrations, service, and the HTTP layer into the runnable subcommands.	Package app wires config, store, migrations, service, and the HTTP layer into the runnable subcommands.
audit Package audit is the audit-model ADR's event vocabulary: the envelope, the closed category.action registry, retention classes, outcome licensing, and the free-text hygiene applied to every attacker-influencable string before it lands in a durable surveillance record.	Package audit is the audit-model ADR's event vocabulary: the envelope, the closed category.action registry, retention classes, outcome licensing, and the free-text hygiene applied to every attacker-influencable string before it lands in a durable surveillance record.
authz Package authz is the authorization chokepoint (permission + tenant-isolation ADRs): authorize(principal, capability-formula, scope) evaluated in-transaction against current policy with no cache, returning a proof-carrying value the store accepts calls only with.	Package authz is the authorization chokepoint (permission + tenant-isolation ADRs): authorize(principal, capability-formula, scope) evaluated in-transaction against current policy with no cache, returning a proof-carrying value the store accepts calls only with.
cli Package cli is the client-side surface: the noun-verb verb table, context resolution, the local trust store, and the output grammar.	Package cli is the client-side surface: the noun-verb verb table, context resolution, the local trust store, and the output grammar.
compose Package compose is the client-side library for Hikyo's Docker Compose delivery path (compose-integration ADR).	Package compose is the client-side library for Hikyo's Docker Compose delivery path (compose-integration ADR).
config Package config parses flags and environment strictly and fail-fast (system-architecture ADR § Tooling defaults): unknown HIKYO_* keys warn, missing prod-critical keys refuse to start, nothing silently conjures a database.	Package config parses flags and environment strictly and fail-fast (system-architecture ADR § Tooling defaults): unknown HIKYO_* keys warn, missing prod-critical keys refuse to start, nothing silently conjures a database.
console Package console renders calm, human-readable messages for Hikyo's terminal surfaces.	Package console renders calm, human-readable messages for Hikyo's terminal surfaces.
crypto Package crypto is the envelope package — the sole crypto chokepoint fixed by the encryption-model ADR and placed here by the system-architecture ADR.	Package crypto is the envelope package — the sole crypto chokepoint fixed by the encryption-model ADR and placed here by the system-architecture ADR.
crypto/backup Package backup owns the age container around an instance export (#76, encryption-model ADR § Backups and exports).	Package backup owns the age container around an instance export (#76, encryption-model ADR § Backups and exports).
definitions Package definitions is the canonical definitions-bundle vocabulary and the pure diffing engine behind `definitions export \| check \| plan \| apply` (source-of-truth ADR, as amended by the flat-model ADR).	Package definitions is the canonical definitions-bundle vocabulary and the pure diffing engine behind `definitions export \| check \| plan \| apply` (source-of-truth ADR, as amended by the flat-model ADR).
delivery Package delivery owns the canonical encodings the machine fetch path keys: the delivery manifest the change token covers, and the tuple the conditional cursor is bound to.	Package delivery owns the canonical encodings the machine fetch path keys: the delivery manifest the change token covers, and the tuple the conditional cursor is bound to.
disclose Package disclose implements the universal print triad (api-cli-surface ADR § Output grammar): every path that can emit secret plaintext sends it to exactly one of three destinations, and refuses otherwise.	Package disclose implements the universal print triad (api-cli-surface ADR § Output grammar): every path that can emit secret plaintext sends it to exactly one of three destinations, and refuses otherwise.
domain Package domain holds the leaf vocabulary shared by the authorization package, the store, and the service layer: tenant identifiers, capability atoms, scopes, and the canonical error sentinels.	Package domain holds the leaf vocabulary shared by the authorization package, the store, and the service layer: tenant identifiers, capability atoms, scopes, and the canonical error sentinels.
dotenv Package dotenv parses a standard `.env` file into ordered key/value entries.	Package dotenv parses a standard `.env` file into ordered key/value entries.
importer Package importer is the client-side import framework (#68, import-paths ADR as amended by the flat-model ADR).	Package importer is the client-side import framework (#68, import-paths ADR as amended by the flat-model ADR).
jwkssource Package jwkssource owns the closed representation and parsing policy for a federation issuer's signing-key source.	Package jwkssource owns the closed representation and parsing policy for a federation issuer's signing-key source.
lint Package lint holds the three custom static analyzers the tenant-isolation ADR fixes (proof signatures, SQL predicate confinement, proof-forgery guard).	Package lint holds the three custom static analyzers the tenant-isolation ADR fixes (proof signatures, SQL predicate confinement, proof-forgery guard).
netpolicy Package netpolicy owns the default-deny public-egress address policy shared by authenticated outbound integrations.	Package netpolicy owns the default-deny public-egress address policy shared by authenticated outbound integrations.
oidcfed Package oidcfed validates externally issued OIDC ID tokens presented as a machine credential (#62, machine-identities ADR § Federation), and owns the server-side JWKS cache with its bounded staleness window.	Package oidcfed validates externally issued OIDC ID tokens presented as a machine credential (#62, machine-identities ADR § Federation), and owns the server-side JWKS cache with its bounded staleness window.
oidcrp Package oidcrp is the OIDC relying-party wrapper: discovery, authorization URL construction, code exchange and complete ID-token validation, all behind go-oidc and golang.org/x/oauth2.	Package oidcrp is the OIDC relying-party wrapper: discovery, authorization URL construction, code exchange and complete ID-token validation, all behind go-oidc and golang.org/x/oauth2.
oidctest Package oidctest is a test-only OpenID Provider: discovery, JWKS, authorization and token endpoints over httptest, RS256-signed ID tokens with caller-controlled claims.	Package oidctest is a test-only OpenID Provider: discovery, JWKS, authorization and token endpoints over httptest, RS256-signed ID tokens with caller-controlled claims.
oidctest/cmd command Command oidctest-idp exposes the internal fake provider to browser-flow tests.	Command oidctest-idp exposes the internal fake provider to browser-flow tests.
operator
operator/api/v1alpha1 Package v1alpha1 defines the Hikyo operator's CustomResourceDefinition Go types: HikyoInstance (cluster-scoped connection configuration) and HikyoSecret (namespaced delivery request).	Package v1alpha1 defines the Hikyo operator's CustomResourceDefinition Go types: HikyoInstance (cluster-scoped connection configuration) and HikyoSecret (namespaced delivery request).
operator/client Package client is the operator's HTTP client for the Hikyo delivery surface.	Package client is the operator's HTTP client for the Hikyo delivery surface.
pathutil Package pathutil centralizes filesystem containment checks.	Package pathutil centralizes filesystem containment checks.
remotefetch Package remotefetch is the directory tier's outbound client (#71, multi-instance ADR § The outbound client).	Package remotefetch is the directory tier's outbound client (#71, multi-instance ADR § The outbound client).
samlsp Package samlsp owns Hikyo's relying-party policy around SAML parsing and identity material.	Package samlsp owns Hikyo's relying-party policy around SAML parsing and identity material.
samltest Package samltest provides a deliberately small SAML IdP fixture for Hikyo's end-to-end tests.	Package samltest provides a deliberately small SAML IdP fixture for Hikyo's end-to-end tests.
scanning Package scanning is the secret-scanning ruleset (ADR docs/adr/secret-scanning.md).	Package scanning is the secret-scanning ruleset (ADR docs/adr/secret-scanning.md).
scanning/bench Package bench is the schema shared by cmd/bench-scan (which writes the result artifact) and the scanning validation test (which parses it).	Package bench is the schema shared by cmd/bench-scan (which writes the result artifact) and the scanning validation test (which parses it).
scanning/corpus Package corpus is the true-positive / false-positive fixture corpus for the secret scanner (ADR §3, SS1).	Package corpus is the true-positive / false-positive fixture corpus for the secret scanner (ADR §3, SS1).
scanning/gen command Command gen produces internal/scanning/rules_gen.go from the vendored gitleaks snapshot plus the committed allowlist.	Command gen produces internal/scanning/rules_gen.go from the vendored gitleaks snapshot plus the committed allowlist.
schema Package schema is the key catalogue's declaration vocabulary and its value-validation engine (#49, schema-model ADR as amended by the flat-model ADR).	Package schema is the key catalogue's declaration vocabulary and its value-validation engine (#49, schema-model ADR as amended by the flat-model ADR).
scimproto Package scimproto is the SCIM 2.0 wire protocol Hikyo implements: the closed resource set, the closed filter grammar, the closed PATCH operation x path matrix, the RFC 7644 error shapes, and the discovery documents.	Package scimproto is the SCIM 2.0 wire protocol Hikyo implements: the closed resource set, the closed filter grammar, the closed PATCH operation x path matrix, the RFC 7644 error shapes, and the discovery documents.
securefile Package securefile owns atomic publication of permission-sensitive files.	Package securefile owns atomic publication of permission-sensitive files.
selfupdate Package selfupdate installs a selected Hikyo release over the current binary.	Package selfupdate installs a selected Hikyo release over the current binary.
server Package server is the HTTP layer: chi router, health surfaces, and the generated API.	Package server is the HTTP layer: chi router, health surfaces, and the generated API.
service Package service is the domain layer.	Package service is the domain layer.
store Package store owns datastore access.	Package store owns datastore access.
store/auditrow Package auditrow is the single audit Row → engine-parameter mapping, shared by the store's audit repositories and the authorization package's denial writer so the two writers cannot drift (audit-model ADR: one envelope-to-column mapping).	Package auditrow is the single audit Row → engine-parameter mapping, shared by the store's audit repositories and the authorization package's denial writer so the two writers cannot drift (audit-model ADR: one envelope-to-column mapping).
store/authn Package authn is the authorization package's enumerated resolution surface (tenant-isolation ADR § bootstrap carve-out): authorize() cannot run under a proof, so the reads it needs to mint one — chain resolution and grant lookup — live here, and nowhere else may read chain tables with request-supplied identifiers.	Package authn is the authorization package's enumerated resolution surface (tenant-isolation ADR § bootstrap carve-out): authorize() cannot run under a proof, so the reads it needs to mint one — chain resolution and grant lookup — live here, and nowhere else may read chain tables with request-supplied identifiers.
store/keyring Package keyring implements crypto.KeyStore over the datastore: every access runs through the transactional boundary, with the hierarchy-generation fence acquired in the same transaction as the writes it fences.	Package keyring implements crypto.KeyStore over the datastore: every access runs through the transactional boundary, with the hierarchy-generation fence acquired in the same transaction as the writes it fences.
store/migrate Package migrate applies the embedded goose migrations.	Package migrate applies the embedded goose migrations.
store/pggen
store/sqlitegen
store/tx Package tx owns the transactional boundary (system-architecture ADR § Transaction boundary).	Package tx owns the transactional boundary (system-architecture ADR § Transaction boundary).
testutil/fixtureref Package fixtureref validates qualified references to executable test fixtures.	Package fixtureref validates qualified references to executable test fixtures.
tlspolicy Package tlspolicy owns Hikyo's inbound certificate loading policy.	Package tlspolicy owns Hikyo's inbound certificate loading policy.
tlstest Package tlstest mints ephemeral certificate chains for inbound TLS tests.	Package tlstest mints ephemeral certificate chains for inbound TLS tests.
updatecheck Package updatecheck selects update notices from Hikyo's release channel.	Package updatecheck selects update notices from Hikyo's release channel.
updater Package updater owns the privileged deployment-helper seam.	Package updater owns the privileged deployment-helper seam.
webauthnrp Package webauthnrp is the WebAuthn relying-party wrapper: ceremony construction and response validation, all behind go-webauthn/webauthn.	Package webauthnrp is the WebAuthn relying-party wrapper: ceremony construction and response validation, all behind go-webauthn/webauthn.
webauthntest Package webauthntest is a test-only software authenticator built on descope/virtualwebauthn.	Package webauthntest is a test-only software authenticator built on descope/virtualwebauthn.
webui Package webui carries the built single-page application, or nothing.	Package webui carries the built single-page application, or nothing.
scripts
ci/analysis-shards-go command
release command Command verify-native-packages proves that each native Linux package is an inert wrapper around the already-built release binary and repository license.	Command verify-native-packages proves that each native Linux package is an inert wrapper around the already-built release binary and repository license.