Repository navigation
Releases
v0.2.0
Six additions for an application that runs beside Kiban. Any active member reads the company's
position and group directories as well as the member one; a position changes hands in one call;
a member can be a guest, present for decisions but shown nobody else; app fragments may say
"and"; decisions read the user's enabled flag straight from Keycloak's database; and merging
the release PR now tags and ships the release.
-
Member-level directories of positions and groups:
GET /api/org/companies/{id}/positionsand.../groupslist id, code and title or name for any active member and an app's service account that is a member, in all three SDKs; the integrate page says to share with a person by granting tomember:<id>#mapped_user -
Decisions read the user's enabled flag from Keycloak's database with one local
SELECT(read-only rolekiban_kcread,KEYCLOAK_DB_NAME), instead of calling the admin REST API on every check; without that database the API answer is cached forKIBAN_USER_STATE_CACHE_SECONDS -
App fragments may use
intersection("and"): a relation that holds only when every child holds, evaluated identically to OpenFGA in the differential harness -
POST /api/org/admin/positions/{id}/handoverends the current assignment and assigns the new member in one transaction, idempotent when the member already holds it, withexpectedAssignmentIdagainst a concurrent administrator; 0.1.x needed two calls and left the position empty in between -
Merging the release PR tags the release: a push to main that changes
VERSIONcreatesv<VERSION>and starts the release workflow; 0.1.x needed a hand-pushed tag -
Guest members:
isGueston a member, set at creation or by a company administrator; a guest is an active member for every decision but is refused the member, position and group directories and a group's member list, so an external person shared with sees nobody else -
Full changelog: https://github.com/rosschiu/kiban/blob/v0.2.0/CHANGELOG.md
-
Known limitations: https://rosschiu.github.io/kiban/latest/limitations/
v0.1.5
Small fixes and three documentation pages from the first audits: modelling practices (a role
matrix as tuples, "and" moved to the writer), folders without exclusion, and module inside or
app beside with the dual-write pattern; the SDK types match the registry, make help exists,
make setup no longer needs openssl, and the README shows how to set Kiban up with a
coding agent.
-
Docs: a page on modelling folders with inherited, broken and limited access using only parent tuples and direct grants, no exclusion
-
Docs: a page on the two integration shapes, module inside Kiban or app beside it, and the grant-first order plus reconciliation sweep an app needs; the limitations page no longer says dependencies are never loaded
-
Docs: a modelling-practices page, structure in the model and policy in the data: a role matrix as tuples, "and" moved to the writer, inheritance without exclusion, and what is a grant versus a re-registration
-
make helplists every target; the contributing pages referred to it and it did not exist -
TypeScript SDK:
Capabilityhasexternal,serviceClientIdandfeatures,CatalogEntryhasexternal,serviceClientIdandfeatures, as the registry already answers them -
make setupgenerates secrets from/dev/urandomwhenopensslis absent; 0.1.4 failed on hosts without it -
README: how to set Kiban up with a coding agent, pointing at
AGENTS.mdwith three starter prompts -
Full changelog: https://github.com/rosschiu/kiban/blob/v0.1.5/CHANGELOG.md
-
Known limitations: https://rosschiu.github.io/kiban/latest/limitations/
v0.1.4
Bugs from the first audits: a module added after the first boot is installed, manifest
dependencies reach the registry, the Node SDK's raw client sends its token, the wire enums know
ASSIGNMENT_ALREADY_ENDED, and the guide stops showing memory storage for a browser login;
plus Go 1.26.10 for a crypto/x509 advisory.
-
Go 1.26.10 toolchain and builder image (GO-2026-6809 in
crypto/x509); 0.1.3 built with 1.26.9 -
ASSIGNMENT_ALREADY_ENDEDis incontracts/wire-enums.jsonand the TypeScript SDK'sApiErrorCode; 0.1.3 answered it from the org service without the contract knowing it -
Node SDK:
AppClient.apisends the service bearer; 0.1.3 sent its requests with no token, so every call through it was401 -
Docs: a browser login needs the default
sessionStorage; the SDK guide showedcreateMemoryStorage()for a login, which cannot complete the redirect -
A module added to
KIBAN_INSTALLED_MODULESafter the first boot is installed on the next restart; 0.1.3 wrote the installation row once and never installed it, so enabling it answered409 MODULE_NOT_INSTALLEDforever -
A module manifest's
dependencies[]are written to the registry at every boot, so a missing one answersMODULE_DEPENDENCY_MISSING; 0.1.3 validated them at build time and then dropped them, so the check never fired -
Full changelog: https://github.com/rosschiu/kiban/blob/v0.1.4/CHANGELOG.md
-
Known limitations: https://rosschiu.github.io/kiban/latest/limitations/
v0.1.3
Fixes from the teams on 0.1.2: positions on org units, the cross-company subject hole in grants,
anchor revoke taking the object's tuples with it, 409 POSITION_HELD with the holder, and the
docs saying plainly that only decisions are revocation-aware; plus the access-token lifetime
from an env var and the documentation site versioned per minor.
-
Assigning a member to a position that already has a holder answers
409 POSITION_HELDwith the currentassignmentIdandmemberIdin the details; 0.1.2 answered a bare409 CONFLICTfrom the database constraint, so the caller could not tell which tenure to end first -
Docs: only decisions are revocation-aware; a verified token alone serves a disabled user until it expires, so the integrate page, the limitations page and the three SDKs' token-verify docs say to make a decision before serving data
-
Positions can be placed on an org unit:
POST /api/org/admin/companies/{id}/positionsaccepts theorgUnitIdthe contract already required (under the company, root when absent), andPUT /api/org/admin/positions/{id}retitles or moves a position; 0.1.2 refusedorgUnitIdwith422and had no update route, so every position sat on the company root -
Grants: revoking an object's anchor removes every other tuple on the object in the same transaction, and the owning app can still revoke tuples 0.1.2 left stranded on an unanchored object; 0.1.2 kept those tuples, refused to revoke them, and revived them when the same id was anchored again
-
Security: a grant naming another company's position, group or member as subject is refused with
422, and a check bound to a company ignores such a subject while expanding; in 0.1.2 a tupleviewer @ position:<B position>#holderon company A's object let a user who is a member of both companies reach A's object -
KIBAN_ACCESS_TOKEN_LIFESPANsets the realm's access-token lifetime in seconds (default 300); 0.1.2 hard-coded it and bootstrap undid any change made in Keycloak -
The documentation site is versioned with
mike: one folder per minor,lateston the newest minor,devfollowing main, a version selector in the header; 0.1.2 served one build of main, and the deploy on a tag failed -
Full changelog: https://github.com/rosschiu/kiban/blob/v0.1.3/CHANGELOG.md
-
Known limitations: https://rosschiu.github.io/kiban/latest/limitations/
v0.1.2
Fixes from the first two teams on 0.1.1: the Kubernetes Secret namespace, batch-can object
fields, registration of a fragment without the company anchor and the grants rule for other apps'
types; plus trusted publishing, the release gate off the advisory feed, and the glue scripts
reduced to one Go tool.
-
Kubernetes: the overlays set
namespace: kiban, the generated and example Secrets carry it, andmake k8s-checkfails on any rendered resource outside it; in 0.1.1 the Secret moved to the overlay without a namespace, landed in the kubeconfig's current one, and every pod waited on it -
batch-canechoes each result'sobjectas{type, id}again; 0.1.1 wrote the Go field namesType/ID, so the Node and Python SDKs returned an empty object on every row (decisions were right; the Go SDK was unaffected because its decoder matches field names case-insensitively); the OpenAPI object reference is now exactly{type, id}and the live OpenAPI run validates it -
App registration refuses a fragment whose object type lacks the
company_moduleanchor with422, nothing stored; before, it registered and every authorization check for every module failed once the app was enabled, because authz validates the anchor only when it loads the fragment -
Grants: an app's service account that is a member of a company can no longer write tuples on another app's object types there; a non-owner app needs the company's
adminrelation (403 COMPANY_ROLE_REQUIREDotherwise), the superadmin exception and the owning app's own types are unchanged -
Release gate no longer runs the advisory scan at the tag (
make check VULNCHECK=0);govulncheckstays on every PR and runs weekly (vulncheck.yml), opening asecurityissue on a finding, so a release never races the advisory feed -
API docs pages load Redoc from Redocly's CDN through one pinned, integrity-checked
<script>instead of inlining the bundle intodocs/api/*.html; the backend SDK trims the gateway origin's trailing slashes without a regex; the remaining code-scanning alerts were triaged with a written reason each -
SDKs publish to npm and PyPI by trusted publishing (OIDC from
release.yml); theNPM_TOKENandPYPI_APIKEYsecrets are no longer read and can be deleted once the publishers are registered on npmjs.com and pypi.org -
The nine manual proof scripts (
infra/e2e-*.sh,modules/*/curl-proof.sh, the restart-survival proof, org'ssmoke.sh) are removed; the-tags liveGo tests and the Playwright suites cover those journeys in the gate. The Python SDK's build output is no longer tracked -
One developer tool,
go run ./tools/dev <subcommand>, replaces the five gate and generator scripts (coverage-gate.sh,kustomize-check.sh,license-scan.sh,pin-images.sh,gen-quickstart-compose.sh),build-api-docs.mjs,cmd/modvalidateand the threetools/*/cmdbinaries; everymaketarget is one line and nothing is CI-only -
No shell in the images: the migrate job and bootstrap set database role passwords over the wire (
go run ./tools/dev migrate,internal/dbrole), the gateway generates its own self-signed development certificate (KIBAN_TLS_SELF_SIGNED_DIR; nogateway-devcertimage, 12 images), the two Postgres init scripts are one, anddeploy/k8s/kiban.sh secrets|applyreplacesgen-secrets.shandapply.sh -
Full changelog: https://github.com/rosschiu/kiban/blob/v0.1.2/CHANGELOG.md
-
Known limitations: https://rosschiu.github.io/kiban/limitations/
v0.1.1
From two integration reviews: a public origin and a standard OIDC issuer for the published
images, second-factor policy and company administrators through the gateway, service accounts
as members, org reads and SDK parity, and package publishing.
-
Go 1.26.9 toolchain and builder image (ten standard-library advisories in
net/http,net/textprotoandcrypto/tls, GO-2026-6603 to GO-2026-6617); the release gate'sgovulncheckblocked the tag on 1.26.8 -
golang.org/x/text0.41.0 (GO-2026-6629, a panic on crafted input in theprecispackage thatpgxreaches on connect); the release gate'sgovulncheckblocked the 0.1.1 tag on 0.40.0 -
Compose marks Keycloak healthy only on a
200readiness status, not on any"status": "UP"fragment; bootstrap's readiness wait grows from 30s to 90s, so a cold firstdocker compose up --waitno longer fails -
Authz debug check answers an engine refusal as
422VALIDATION_FAILED(was theVALIDATION_ERRORshape code) -
Quickstart "What to try first" points at the admin routes instead of a removed section
-
The discovery document's
issuerequals theissevery token carries (<origin>/realms/<realm>) at both/auth/realms/…and/realms/…, so a standard OpenID Connect library accepts Kiban's tokens; the/realms/mount forwards Keycloak untouched, so a login started there completes -
An object carries one company anchor: the grants route refuses a second anchor with
422and migrationauthz/0012adds the unique index behind it; a repeated tuple is still a no-op; the grant ledger records changes only (a duplicate grant or a revoke of a missing tuple no longer writes a phantom row) -
Kubernetes:
apply.shwaits only for the Deployments the overlay created, so a core-only apply no longer fails on the absent sample modules; the gateway receivesKIBAN_DOMAINandKIBAN_EXTRA_ORIGINSfromkiban-config, as bootstrap already did -
The Kustomize base carries no Secret, so it works as a remote base from another repository; each overlay supplies
kiban-secrets(gen-secrets.sh <overlay>writes it there and moves a 0.1.0base/secret.yamlinto place);make k8s-checkrenders base and overlays without a cluster -
Zero-clone quickstart serves a real origin:
deploy/quickstart/compose.public.yaml(generated from the source overlay) sets the public issuer, Keycloak hostname,KIBAN_DOMAINandKIBAN_TRUSTED_PROXYfrom oneKIBAN_PUBLIC_HOST -
Second-factor policy through the gateway:
GET/PUT /api/platform/admin/mfa-policy/global,GET/PUT/DELETE .../users/{subject},POST .../sync(superadmin); documented on the Operating page, with the note that a new realm requires no second factor -
Members carry
kind(personorservice): identity records whether a user is a client's service account (confirmed through Keycloak's client link at provisioning), and the member directory and admin member routes return it; bootstrap grants identity's service account the read-onlyview-clientsrole for that check and repairs it on an existing realm -
Docs: an app's service account is a user; to run background jobs in a company it must be made a member of that company (the two admin calls), while writing tuples on the app's own types needs no membership
-
A company's administrator (
company:<id>#admin) manages that company's members, positions, assignments and groups through/api/org/admin/*; the gateway and org both decide "superadmin, or administrator of this company"; companies and org units stay superadmin work -
Two company reads for apps and members: a position's holder on a date (
GET /api/org/companies/{id}/positions/{positionId}/holder?date=) and a group's members, for any active member of the company or a superadmin, never across companies -
SDK parity: batch checks, companies the user may see, member directory, position holder and group members in the Go, Node (
server) and Python SDKs; Python gainsbatch_can -
Each sample module has its own Compose profile beside
samples:COMPOSE_PROFILES=docsstarts one container, not four -
Releases publish
kiban-sdkto PyPI and@rossbsol/kiban-sdkto the public npm registry when the repository holdsPYPI_APIKEYandNPM_TOKEN; both packages are also attached to the workflow run as artifacts. The npm package is renamed from@rosschiu/kiban-sdk(never published publicly) and GitHub Packages is no longer used -
Full changelog: https://github.com/rosschiu/kiban/blob/v0.1.1/CHANGELOG.md
-
Known limitations: https://rosschiu.github.io/kiban/limitations/
v0.1.0
First public release, Apache-2.0. Kiban runs beside your app: the app registers its model and
serves its own API; the sample modules are examples, off by default.
- Backend SDKs:
@rosschiu/kiban-sdk/server(Node),kiban-sdk(Python),github.com/rosschiu/kiban/sdk(Go): service token, user token verification, decisions, tuples, member lookup, app registration - Kiban repositioned as a service beside your app (OpenFGA-style): the app registers its model and serves its own API; the module runtime is the sample modules' in-tree path
KIBAN_EXTRA_ORIGINS: extra web origins and native (custom-scheme) redirect URIs forkiban-frontend, also on the gateway's CORS allow-list; a Flutter or second web app can log in- Apps register at runtime (
POST /api/platform/admin/apps, manifest with fragment, features and service client); an app's backend writes tuples on its own types and looks up members; a check names only a feature its module declares (one string, one feature) - Company, org-unit and member administration through the gateway (
/api/org/admin/units,/api/org/admin/members) - The four sample modules are optional:
COMPOSE_PROFILES=samplesandKIBAN_INSTALLED_MODULESbring them up; the default stack is the foundation only and the gateway no longer waits on them - Service credential:
KIBAN_SERVICE_CLIENTScreates confidential Keycloak clients whose client-credentials tokens the gateway accepts, for workers and connectors - Identity: embedded Keycloak, OpenID Connect with PKCE, MFA policy (authenticator app or passkey), bootstrap seeds the superadmin with a file-delivered password
- Organization: org-unit tree, members, positions and groups; company is the sole authorization anchor; cross-company facts are unrepresentable
- Authorization: Postgres-native Zanzibar-subset engine, differential-tested against OpenFGA; modules ship an authorization fragment
- Position- and group-based access: rights follow the position holder or group membership with zero permission edits
- Audit: every mutation writes an append-only audit row in the same transaction
- Module runtime: manifest, fragment, OpenAPI file, checksummed migrations; validated by
make validate-modules, routed by a version-blind gateway - Gateway: single origin, bearer-only
/api/*, CORS, security headers, request limits,/readyhealth - Sample modules: notification, docs (DocShare), helpdesk, timesheet
- SDK
@rosschiu/kiban-sdk: session with PKCE and refresh, API client, org and effective-access clients,canIand grant recipes - Sample shell: React, CSP enforced, company switcher, administration pages
- Platform role is one tuple (
system:platform#superadmin) with grant and revoke routes GET /api/platform/metricsaggregates every service's metrics for one scrape target- Postgres roles: non-superuser owner
kiban, per-service roles, secrets read from files - Containers run as uid 65532, read-only root, no capabilities; base images digest-pinned
- Compose is the supported deployment; Kubernetes manifests proven on kind only
- Coverage ratchet, OpenAPI response validation, licence and secret scans in
make check - Documentation site: quickstart, integrate, concepts, building, SDK guide, operating, security, limitations
- Full changelog: https://github.com/rosschiu/kiban/blob/v0.1.0/CHANGELOG.md
- Known limitations: https://rosschiu.github.io/kiban/limitations/