kiban

module
v0.1.1 Latest Latest
Warning

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

Go to latest
Published: Oct 6, 2026 License: Apache-2.0

README

Kiban (基盤)

CI

Self-hostable identity, organization and authorization for business applications. Kiban runs beside your app, in your environment, and answers three questions for every request: who is this (login through an embedded Keycloak, your identity provider federated in), where do they sit (companies, members, positions, groups) and what may they do (a relationship-based authorization engine in the family of Zanzibar and OpenFGA, with an immutable audit trail). Your app keeps its own code, database and deployment, and calls Kiban through an SDK.

Documentation: https://rosschiu.github.io/kiban/ (source in docs/; make docs-site builds it locally). Start with the quickstart to run it, Integrate your app for the backend and frontend steps, and known limitations for what 0.1 cannot do. AGENTS.md gives a coding agent the same reading order and the rules of the tree.

What it does

  • Identity: an embedded Keycloak instance (OpenID Connect with PKCE; authenticator-app or passkey MFA policy, global or per user, where a per-user override can only raise it) synced to a Postgres identity store; a user is provisioned on their first request. Your existing identity provider federates in as a login source. A backend gets its own credential: a confidential service client whose token the gateway accepts.
  • Organization: a typed org-unit tree, members, positions and groups, with the company as the sole authorization anchor. Integrity is enforced in the database: cross-company facts are unrepresentable, concurrent tree writes are serialized, a company's id is immutable.
  • Authorization: a Postgres-native Zanzibar-subset engine (relation tuples plus a declarative model), compared against OpenFGA in the test suite. Your app registers its own object types and relations on top of the base model, writes tuples on them, and asks for decisions. Every object check is bound to the request's company; the superadmin role is one revocable tuple.
  • Position-based and group-based access: grant to a position and whoever holds it has the access; grant to a group and every current member has it. Reassignments and membership changes need no permission edits.
  • Audit: every mutation writes its audit event in the same transaction into append-only tables, with the actor taken from the verified token and the request's correlation id.
  • SDKs: TypeScript for the browser (login, session, typed calls) and for Node backends, Python and Go for backends. Each backend SDK does the same five things: obtain the app's service token, verify a user's token, ask for decisions, write and remove tuples on the app's own types, look members up.

Four sample modules ship in the repository as worked examples of a deeper integration (notification, docs, helpdesk, timesheet); they are off by default.

Stack: Go (standard library net/http), Postgres 18, Keycloak 26, a TypeScript SDK and a React sample shell (npm workspaces), Docker Compose. Kubernetes manifests exist under deploy/k8s/ and are proven on a local kind cluster only.

Quickstart

Needs docker (with the Compose plugin) and make on a Linux x86_64 host. Every service builds inside containers.

make setup   # checks docker, writes .env with generated secrets (once), creates infra/secrets-in/
make dev     # builds and starts every container, waits until all are healthy

Kiban is then at https://127.0.0.1:8443 (self-signed certificate). Log in as KIBAN_SUPERADMIN_USERNAME from .env (default superadmin) with the password in infra/secrets-in/superadmin-password (a 0600 file written once, never printed to a log; the first login makes you change it). make dev-down stops it and keeps data; make dev-clean also removes the volumes.

A checkout-free variant lives in deploy/quickstart/: it pulls the foundation images only (no gateway-devcert, no sample modules).

Requirements

  • Linux, x86_64 (what the project builds and tests on).
  • Docker Engine 29 and Compose v5 or newer.
  • About 4 GB RAM and 2 cores as a practical floor (the idle stack uses about 1.2 GB, mostly Keycloak); 10 GB free disk for images, volumes and data growth.

Development

make test-stack-up   # isolated test stack (compose project kiban-test, its own ports and volumes)
make check           # format, vet, vulnerability check, unit tests, module and migration validation, web checks, coverage ratchet (40 scopes), licence and secret scans
make test            # full tests, including live-tagged tests and the OpenFGA differential harness

Coverage is enforced by a per-package ratchet whose minimums only rise. Browser end-to-end tests (Playwright) target the isolated stack only; a guard refuses to run them against a live deployment. See CONTRIBUTING.md.

Operating

Every service exposes Prometheus metrics on its internal listener; the gateway also serves its own at GET /api/platform/metrics for a superadmin bearer. Upgrades, backup and restore, TLS modes and identity federation are covered in the documentation's Operating Kiban page.

Status and limitations

Version 0.1. Read the documentation's Known limitations page before relying on anything; it lists what is not built or not yet right.

Licence

Apache-2.0, copyright 2026 Ross Chiu, for the whole tree: foundation, sample modules, module kit, SDK and documentation. See LICENSING.md for the path map and SECURITY.md for reporting vulnerabilities.

Maintainer

Kiban is maintained by Ross Chiu (@rosschiu). Security contact: see SECURITY.md. Licence: LICENSING.md.

Directories

Path Synopsis
cmd
authz command
Command authz runs kiban-authz: the authz service (subset-walled fragment-loaded engine, transactional grant API, the layered fail-closed effective-access decision).
Command authz runs kiban-authz: the authz service (subset-walled fragment-loaded engine, transactional grant API, the layered fail-closed effective-access decision).
bootstrap command
Command bootstrap runs kiban-bootstrap: the one-shot container that converges a deployment.
Command bootstrap runs kiban-bootstrap: the one-shot container that converges a deployment.
gateway command
Command gateway runs kiban-gateway, the edge service.
Command gateway runs kiban-gateway, the edge service.
identity command
Command identity runs kiban-identity: the identity service (canonical Keycloak-subject-keyed user records, platform roles, login observation, MFA policy layering synced to Keycloak).
Command identity runs kiban-identity: the identity service (canonical Keycloak-subject-keyed user records, platform roles, login observation, MFA policy layering synced to Keycloak).
modvalidate command
Command modvalidate is the module-artifact validator: it loads one or more module directories, validates every artifact against the module contract's reject list, and exits non-zero on the first batch that has any named error.
Command modvalidate is the module-artifact validator: it loads one or more module directories, validates every artifact against the module contract's reject list, and exits non-zero on the first batch that has any named error.
org command
Command org runs kiban-org: the org service (the triangle — typed org-unit tree, company-scoped members with optional user link, position slots).
Command org runs kiban-org: the org service (the triangle — typed org-unit tree, company-scoped members with optional user link, position slots).
registry command
Command registry runs kiban-registry: the platform registry service (module catalog / installation / dependency state, the capability API, tenant defaults, seed-missing-only bootstrap seeding).
Command registry runs kiban-registry: the platform registry service (module catalog / installation / dependency state, the capability API, tenant defaults, seed-missing-only bootstrap seeding).
internal
audit
Package audit is the platform's ONE audit writer: every service writes its own audit.<module>__* table through this package instead of hand-rolling INSERT statements per service.
Package audit is the platform's ONE audit writer: every service writes its own audit.<module>__* table through this package instead of hand-rolling INSERT statements per service.
authz
Package authz wires the authz service: the fragment-loaded engine, the transactional grant store, the effective-access decision, and their HTTP surface.
Package authz wires the authz service: the fragment-loaded engine, the transactional grant store, the effective-access decision, and their HTTP surface.
authz/client
Package client is the shared "is this caller the platform superadmin" AdminAuthorizer implementation, used by org, identity, registry and the gateway's superadmin guard.
Package client is the shared "is this caller the platform superadmin" AdminAuthorizer implementation, used by org, identity, registry and the gateway's superadmin guard.
authz/decision
Package decision implements the effective-access decision EXACTLY: the ordered 8-step, fail-closed effective-access decision, the 13-reason enum (OPENFGA_DENIED is named ENGINE_DENIED here — the engine is not OpenFGA), and evidence/batchCan semantics.
Package decision implements the effective-access decision EXACTLY: the ordered 8-step, fail-closed effective-access decision, the 13-reason enum (OPENFGA_DENIED is named ENGINE_DENIED here — the engine is not OpenFGA), and evidence/batchCan semantics.
authz/engine
Package engine is the evaluator for the supported Zanzibar subset (this, computedUserset, tupleToUserset, union).
Package engine is the evaluator for the supported Zanzibar subset (this, computedUserset, tupleToUserset, union).
authz/fragment
Package fragment loads module authz fragments (a module's authz.fragment.json "relations" JSON) into the effective engine.Model, subset-walled and inert for modules the registry doesn't know about or has disabled: an unknown/disabled module's fragment contributes NOTHING to the effective model, and — the property this package exists to prove — a check against an object type that belongs ONLY to such a fragment answers false, never errors, never allows.
Package fragment loads module authz fragments (a module's authz.fragment.json "relations" JSON) into the effective engine.Model, subset-walled and inert for modules the registry doesn't know about or has disabled: an unknown/disabled module's fragment contributes NOTHING to the effective model, and — the property this package exists to prove — a check against an object type that belongs ONLY to such a fragment answers false, never errors, never allows.
authz/store
The default module-access tuple writer.
The default module-access tuple writer.
bootstrap
Package bootstrap implements the kiban-bootstrap step runner: an ordered set of idempotent, individually-logged steps (preflight, migrations orchestration, realm reconciliation, service accounts, superadmin, seed, verify) that each report a truthful applied|converged|failed outcome.
Package bootstrap implements the kiban-bootstrap step runner: an ordered set of idempotent, individually-logged steps (preflight, migrations orchestration, realm reconciliation, service accounts, superadmin, seed, verify) that each report a truthful applied|converged|failed outcome.
config
Package config loads configuration from environment variables, with support for *_FILE secret-file variants that take precedence over the plain env var when both are set.
Package config loads configuration from environment variables, with support for *_FILE secret-file variants that take precedence over the plain env var when both are set.
errenv
Package errenv defines the platform's error and success envelope shapes, the canonical error codes, and HTTP writers for both.
Package errenv defines the platform's error and success envelope shapes, the canonical error codes, and HTTP writers for both.
gateway
The sample shell's minimal group admin surface — the position admin slice pattern applied to groups.
The sample shell's minimal group admin surface — the position admin slice pattern applied to groups.
httpx
Package httpx provides plumbing-only HTTP middleware shared across services: correlation-id propagation, panic recovery, and access logging.
Package httpx provides plumbing-only HTTP middleware shared across services: correlation-id propagation, panic recovery, and access logging.
identity
The real AdminAuthorizer, replacing denyAllAuthorizer in production.
The real AdminAuthorizer, replacing denyAllAuthorizer in production.
livestack
Package livestack is a shared guard that live-dependent test helpers and the infra/e2e-*.sh / modules/*/curl-proof.sh scripts use to detect when the deployment they would otherwise mutate is the PUBLIC stack (`make public-up`) rather than an isolated one: `make check`/`make test` must never mutate a deployment a human is using (test runs against a public deployment can revert realm redirect URIs, restore required actions, and truncate org tables).
Package livestack is a shared guard that live-dependent test helpers and the infra/e2e-*.sh / modules/*/curl-proof.sh scripts use to detect when the deployment they would otherwise mutate is the PUBLIC stack (`make public-up`) rather than an isolated one: `make check`/`make test` must never mutate a deployment a human is using (test runs against a public deployment can revert realm redirect URIs, restore required actions, and truncate org tables).
modvalidate
SPDX-License-Identifier: Apache-2.0
SPDX-License-Identifier: Apache-2.0
obs
Package obs provides the platform's structured logger: a JSON slog handler to stderr with correlation-id awareness.
Package obs provides the platform's structured logger: a JSON slog handler to stderr with correlation-id awareness.
obs/metrics
Package metrics is the platform's Prometheus exposition package: one Registry per service process, built once in that service's main and threaded through to (a) an HTTP middleware wrapped directly around the service's own mux (b) a GET /metrics handler on the service's own listener and (c) whichever service-specific Record*/Observe* calls that service's own code needs (authz's decision path, notification's delivery worker, the gateway's module proxy).
Package metrics is the platform's Prometheus exposition package: one Registry per service process, built once in that service's main and threaded through to (a) an HTTP middleware wrapped directly around the service's own mux (b) a GET /metrics handler on the service's own listener and (c) whichever service-specific Record*/Observe* calls that service's own code needs (authz's decision path, notification's delivery worker, the gateway's module proxy).
org
The production AdminAuthorizer.
The production AdminAuthorizer.
pgconv
Package pgconv holds the nullable-column conversions every pgx-backed store repeats.
Package pgconv holds the nullable-column conversions every pgx-backed store repeats.
registry
The real AdminAuthorizer (service.go's interface).
The real AdminAuthorizer (service.go's interface).
testauditgolden
Package testauditgolden is a shared helper for golden tests of audit event PAYLOAD SHAPE (keys + JSON value types, never values themselves — an audit payload routinely carries real member/company/document IDs and titles that must never be pinned verbatim into a checked-in fixture).
Package testauditgolden is a shared helper for golden tests of audit event PAYLOAD SHAPE (keys + JSON value types, never values themselves — an audit payload routinely carries real member/company/document IDs and titles that must never be pinned verbatim into a checked-in fixture).
testchaos
Package testchaos provides shared "dependency down" fake upstream servers for chaos tests: every module's HTTP layer must prove fail-closed (authz-down -> 503 AUTHORIZATION_UNAVAILABLE, org-down -> 503, never a fallback to stale data) and, where the module's design says so, fail-open-by-design (notification-down must not fail the business write it's attached to).
Package testchaos provides shared "dependency down" fake upstream servers for chaos tests: every module's HTTP layer must prove fail-closed (authz-down -> 503 AUTHORIZATION_UNAVAILABLE, org-down -> 503, never a fallback to stale data) and, where the module's design says so, fail-open-by-design (notification-down must not fail the business write it's attached to).
testopenapi
Package testopenapi is a reusable helper: load a module's openapi.yaml fragment once, then validate RECORDED handler-test responses (status + body) against the operation the request actually matched, so the running service is proven to honor its contract at the HTTP boundary.
Package testopenapi is a reusable helper: load a module's openapi.yaml fragment once, then validate RECORDED handler-test responses (status + body) against the operation the request actually matched, so the running service is proven to honor its contract at the HTTP boundary.
testsec
Package testsec is the shared negative-security matrix: one place that generalizes the ad hoc 401/403/503/forged-header pattern internal/gateway/admin_position_routes_test.go and admin_group_routes_test.go established, so every guarded route in the gateway and all four module HTTP layers is proven, not just the ones a human remembered to hand-write a matrix for.
Package testsec is the shared negative-security matrix: one place that generalizes the ad hoc 401/403/503/forged-header pattern internal/gateway/admin_position_routes_test.go and admin_group_routes_test.go established, so every guarded route in the gateway and all four module HTTP layers is proven, not just the ones a human remembered to hand-write a matrix for.
version
Package version carries the platform's own build identity — Version (the VERSION file's contents, e.g.
Package version carries the platform's own build identity — Version (the VERSION file's contents, e.g.
Package licensetext embeds the canonical full-text license bodies a module manifest's license class may declare.
Package licensetext embeds the canonical full-text license bodies a module manifest's license class may declare.
Package modulekit is the scaffolding every Kiban module service needs and used to copy: bearer verification, the small HTTP/pg helpers, and thin clients for org's member facts, authz's effective-access/grants API and notification's targeted-events API.
Package modulekit is the scaffolding every Kiban module service needs and used to copy: bearer verification, the small HTTP/pg helpers, and thin clients for org's member facts, authz's effective-access/grants API and notification's targeted-events API.
kittest
Package kittest is the test JWKS issuer a module's tests use to mint bearers for modulekit.TokenVerifier: an RSA key pair, an httptest JWKS server and a signer.
Package kittest is the test JWKS issuer a module's tests use to mint bearers for modulekit.TokenVerifier: an RSA key pair, an httptest JWKS server and a signer.
modules
docs
Package docsartifacts embeds the module's contract artifacts that a Go binary needs at compile time.
Package docsartifacts embeds the module's contract artifacts that a Go binary needs at compile time.
docs/service
AuthzClient talks to authz's real effective-access decision (POST /internal/authz/ effective-access/can and /batch-can, the pattern every module uses) plus the grants S2S surface (POST /internal/authz/grants, op:"grant"|"revoke") — this module's ONLY path to writing/removing authz tuples (modules never write authz.* tables directly).
AuthzClient talks to authz's real effective-access decision (POST /internal/authz/ effective-access/can and /batch-can, the pattern every module uses) plus the grants S2S surface (POST /internal/authz/grants, op:"grant"|"revoke") — this module's ONLY path to writing/removing authz tuples (modules never write authz.* tables directly).
docs/service/cmd command
Command docs runs kiban-docs: the DocShare module service's HTTP API (fine-grained, per-document sharing).
Command docs runs kiban-docs: the DocShare module service's HTTP API (fine-grained, per-document sharing).
helpdesk
Package helpdeskartifacts embeds the module's contract artifacts that a Go binary needs at compile time.
Package helpdeskartifacts embeds the module's contract artifacts that a Go binary needs at compile time.
helpdesk/service
AuthzClient calls authz's POST /internal/authz/effective-access/can (per-operation decisions, the pattern every module uses) plus POST /internal/authz/grants (agent designation: this module's agents API wraps the existing grants surface, never a parallel grant store).
AuthzClient calls authz's POST /internal/authz/effective-access/can (per-operation decisions, the pattern every module uses) plus POST /internal/authz/grants (agent designation: this module's agents API wraps the existing grants surface, never a parallel grant store).
helpdesk/service/cmd command
Command helpdesk runs kiban-helpdesk: the helpdesk module service's HTTP API (ticket workflow).
Command helpdesk runs kiban-helpdesk: the helpdesk module service's HTTP API (ticket workflow).
notification
Package notificationartifacts embeds notification's module-contract artifacts that a Go binary needs at compile time (the registry's install path needs the module's authz.fragment.json bytes to seed authz.model_fragment, and cmd/registry's container has no filesystem access to modules/ at runtime).
Package notificationartifacts embeds notification's module-contract artifacts that a Go binary needs at compile time (the registry's install path needs the module's authz.fragment.json bytes to seed authz.model_fragment, and cmd/registry's container has no filesystem access to modules/ at runtime).
notification/service
notification's per-operation authorization goes through authz's real effective-access decision (POST /internal/authz/effective-access/can), with the fragment's own object-relation leg (step 7 of the ordered decision) for the two tiers that need it.
notification's per-operation authorization goes through authz's real effective-access decision (POST /internal/authz/effective-access/can), with the fragment's own object-relation leg (step 7 of the ordered decision) for the two tiers that need it.
notification/service/cmd command
Command notification runs kiban-notification: the notification module service — channels/subscriptions/messages/inbox HTTP API plus the leased delivery worker, in one process (the module manifest names one service.port; the worker is an in-process background loop, not a second binary).
Command notification runs kiban-notification: the notification module service — channels/subscriptions/messages/inbox HTTP API plus the leased delivery worker, in one process (the module manifest names one service.port; the worker is an in-process background loop, not a second binary).
timesheet
Package timesheetartifacts embeds timesheet's module-contract artifacts that a Go binary needs at compile time (same rationale as modules/notification/artifacts.go — the registry's install path needs the module's authz.fragment.json bytes to seed authz.model_fragment, and cmd/registry's container has no filesystem access to modules/ at runtime).
Package timesheetartifacts embeds timesheet's module-contract artifacts that a Go binary needs at compile time (same rationale as modules/notification/artifacts.go — the registry's install path needs the module's authz.fragment.json bytes to seed authz.model_fragment, and cmd/registry's container has no filesystem access to modules/ at runtime).
timesheet/service
AuthzClient calls authz's POST /internal/authz/effective-access/can (per-operation decisions) and POST /internal/authz/grants (submitter/approver designation — this module's approvers API wraps the existing grants surface, never a parallel grant store).
AuthzClient calls authz's POST /internal/authz/effective-access/can (per-operation decisions) and POST /internal/authz/grants (submitter/approver designation — this module's approvers API wraps the existing grants surface, never a parallel grant store).
timesheet/service/cmd command
Command timesheet runs kiban-timesheet: the timesheet module service — projects, entries, submissions/approvals, and configuration, built solely against the module contract using modules/notification's service layout as the reference (authz decision calls, http auth pattern, store/tx/audit discipline).
Command timesheet runs kiban-timesheet: the timesheet module service — projects, entries, submissions/approvals, and configuration, built solely against the module contract using modules/notification's service layout as the reference (authz decision calls, http auth pattern, store/tx/audit discipline).
Package sdk is the Go client for an application that runs beside Kiban: the app's backend authenticates as its registered service client, verifies the user tokens Kiban's login issued, asks for access decisions, writes and removes relation tuples on the app's own object types, and looks members up — all through the gateway's public API, never by network position.
Package sdk is the Go client for an application that runs beside Kiban: the app's backend authenticates as its registered service client, verifies the user tokens Kiban's login issued, asks for access decisions, writes and removes relation tuples on the app's own object types, and looks members up — all through the gateway's public API, never by network position.
tools
coveragegate command
Command coveragegate implements the coverage ratchet: it parses Go and web coverage profiles, aggregates them into the scopes listed in `scopes` below, and compares each scope's current statement coverage against coverage/ratchet.json.
Command coveragegate implements the coverage ratchet: it parses Go and web coverage profiles, aggregates them into the scopes listed in `scopes` below, and compares each scope's current statement coverage against coverage/ratchet.json.
licensecheck
Package licensecheck implements the SPDX header sweep: every first-party source file (Go, TS/TSX, SQL, shell) must carry a `SPDX-License-Identifier: <id>` line matching its directory's license, per LICENSING.md's path->license map.
Package licensecheck implements the SPDX header sweep: every first-party source file (Go, TS/TSX, SQL, shell) must carry a `SPDX-License-Identifier: <id>` line matching its directory's license, per LICENSING.md's path->license map.
licensecheck/cmd command
Command licensecheck is `make license-check`'s SPDX header verifier: walks the repo from the current working directory (expected to be the repo root — the Makefile invokes it that way), checks every first-party Go/TS/TSX/SQL/shell file against tools/licensecheck's zone rules, and fails loudly (exit 1) listing every file missing its header.
Command licensecheck is `make license-check`'s SPDX header verifier: walks the repo from the current working directory (expected to be the repo root — the Makefile invokes it that way), checks every first-party Go/TS/TSX/SQL/shell file against tools/licensecheck's zone rules, and fails loudly (exit 1) listing every file missing its header.
ratchetguard
Package ratchetguard implements the mechanical never-decrease check for coverage/ratchet.json (minimums may only ever increase, never decrease).
Package ratchetguard implements the mechanical never-decrease check for coverage/ratchet.json (minimums may only ever increase, never decrease).
ratchetguard/cmd command
Command ratchetguard fails (exit 1) if any coverage/ratchet.json scope's "min" was lowered or any scope was removed — the comparison itself lives in tools/ratchetguard (unit-tested there without any git dependency).
Command ratchetguard fails (exit 1) if any coverage/ratchet.json scope's "min" was lowered or any scope was removed — the comparison itself lives in tools/ratchetguard (unit-tested there without any git dependency).

Jump to

Keyboard shortcuts

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