Skip to content

feat: client libraries for Go, Python and TypeScript, GitHub Action and GitLab CI template - #914

Merged
rubenvdlinde merged 9 commits into
developmentfrom
feat/apps-client-libraries-and-ci
Oct 2, 2026
Merged

rubenvdlinde merged 9 commits into
developmentfrom
feat/apps-client-libraries-and-ci

Conversation

@rubenvdlinde

Copy link
Copy Markdown
Contributor

Closes #776

Builds the OpenSpec change apps-client-libraries-and-ci and archives it. Parity rows apps-18 and apps-21 move to built.

What changed

  • Go library (sdk/go/, module github.com/ConductionNL/keepiq/sdk/go). The CLI's internal/client and internal/crypto move here, so other Go programs can import them. New keepiq.New(url, applicationId, privateKeyPem) with GetByName, GetByID, List(updatedSince), Create and Update. It caches the token, sends If-None-Match, exposes the lease, and raises typed errors (not found, unauthorized, not modified, ambiguous name with candidates, key mismatch). Stdlib only.
  • Python library (sdk/python/, keepiq-sdk) and TypeScript library (sdk/js/, @conduction/keepiq-sdk, WebCrypto, no runtime dependency). Same surface.
  • Shared vectors in sdk/testdata/: the serializer envelope (moved from cli/testdata/), the browser vector (moved from cli/internal/crypto/testdata/), and one vector encrypted by each library. Every library decrypts every vector. tests/Unit/Service/SdkEncryptedVectorsTest.php decrypts each library's vector with DecryptService. .gitleaks.toml allow-lists ^sdk/testdata/.
  • CLI: keepiq ci fetch and ci run now run on keepiq.Client, so they read the canonical discovery document. ci run no longer passes KEEPIQ_APP_KEY to the wrapped command.
  • GitHub Action (integrations/github-action/): checksum-verified install, run mode through keepiq ci run, opt-in export-env that masks every line first. Without either it fails and names both.
  • GitLab template (integrations/gitlab-ci/keepiq.gitlab-ci.yml): hidden .keepiq job with a checksum-verified install.
  • Workflows: sdk.yml (tests, dry-run packaging, publish on sdk/go/v*, sdk-py-v*, sdk-js-v*), integrations.yml (the action and the template against a stub Keepiq), and cli-release.yml gains SHA256SUMS and the ghcr.io/conductionnl/keepiq-cli image. It now also runs on sdk/go changes.
  • Docs: docs/client-libraries.md, docs/ci-integrations.md, sdk/README.md.

Verified here

  • go vet and go test ./... in sdk/go and cli (golang:1.22): green.
  • python -m unittest discover -s tests in sdk/python: 14 green.
  • vitest run in sdk/js: 15 green; tsc --noEmit clean.
  • phpunit --filter 'SdkEncryptedVectorsTest|MachineEnvelopeCliFixtureTest': 4 green.
  • integrations/test/run.sh with a CLI built from this branch: 9 checks green (run mode, no file holds the value, NAME=ENV_VAR, masked multi-line export, both options named, tampered binary refused, missing version, GitLab job, GitLab tampered binary).
  • cli/Dockerfile built locally from the linux binary; docker run ... --version answered.

Refusal tests: the wrong-key, not-found, ambiguous-name, key-mismatch and unknown-field tests in each library fail when the guard is removed. TestChildEnvironDropsTheApplicationKey fails on the old runChild.

Owed

  • Live: keepiq ci fetch <name> against the dev instance with a registered application (task 1.2).
  • CI runs: the sdk.yml, integrations.yml and cli-release.yml dry runs on this PR; reading the masked value in the integrations.yml log.
  • Publishing (not done here, by design): PyPI trusted publisher setup and the first sdk-py-v* tag; NPM_TOKEN and the first sdk-js-v* tag; the first sdk/go/v* tag; the first cli-v* release with SHA256SUMS and the ghcr image.
  • A gitleaks run, a GitLab CI lint call, and the docs build (all need tooling not installed here).

Design notes: the certificate fingerprint check needs the application's certificate, which the key alone cannot produce, so each library takes it as an option and checks it against the key. go install github.com/ConductionNL/keepiq/cli@... stops working because of the replace directive; the CLI ships as release binaries and the image.

Checks

Checks: pending, coordinator runs check.sh.

Inherited findings: none seen in the files this PR touches; the PHPUnit "no code coverage driver" warning is the same on development.

🤖 Generated with Claude Code

The CLI's internal client and crypto packages move to
github.com/ConductionNL/keepiq/sdk/go so other Go programs can import
them; the CLI builds against it through a replace directive and both
stay stdlib only. The shared vectors move to sdk/testdata/. The crypto
package gains EncryptField (the inverse of DecryptField, same recipe as
EncryptService) and accepts PKCS#1 keys.

Refs #776
…ctors

sdk/go now offers keepiq.New(url, applicationId, privateKeyPem) with
GetByName, GetByID, List(updatedSince), Create and Update. It discovers
the instance, signs the RFC 7523 assertion, caches the token, sends
If-None-Match and reports not modified, exposes the lease headers, and
raises typed errors (not found, unauthorized, ambiguous name with
candidates, key mismatch). Writes encrypt every value field to the
caller's own key before sending.

sdk/testdata gains vector_plaintexts.json and the Go-encrypted vector;
SdkEncryptedVectorsTest decrypts it with DecryptService. The test key
path is allow-listed for gitleaks.

Refs #776
sdk/python is the keepiq-sdk package on cryptography only, with the same
surface as the Go library (get_by_name, get_by_id, list, create, update,
typed errors, ETag, lease, token cache). Its tests run against a stub
Keepiq in sdk/testdata/stub_server.py and the shared vectors, including
the browser's own vector; the Python-encrypted vector is decrypted by
DecryptService in SdkEncryptedVectorsTest.

keepiq ci fetch and ci run now use keepiq.Client from sdk/go, so the CLI
reads the canonical discovery document and resolves its endpoints the
same way as the libraries.

Refs #776
sdk/js is @conduction/keepiq-sdk with the same surface as the Go and
Python libraries. It runs on Node 20+ and in browsers, wraps PKCS#1
keys into PKCS#8 for WebCrypto, and checks a configured certificate
against the key by its SubjectPublicKeyInfo. Its vitest suite runs
against a node stub of the machine API and the shared vectors; the
TypeScript-encrypted vector is decrypted by DecryptService, and every
library now decrypts every other library's vector.

Refs #776
…ecrets

integrations/github-action is a composite action. It installs the CLI
for the runner from a cli-v* release, refuses a binary whose SHA-256
does not match the release SHA256SUMS, and then either runs a command
through keepiq ci run (nothing on disk) or, with export-env: true,
masks every line of every value before appending it to GITHUB_ENV.
Without either it fails and names both options. NAME=ENV_VAR picks the
variable name.

integrations/gitlab-ci/keepiq.gitlab-ci.yml defines the hidden .keepiq
job that installs the checksum-verified CLI for keepiq ci run.

keepiq ci run no longer passes KEEPIQ_APP_KEY to the wrapped command:
the command gets its secrets, not the key that reads every secret.

integrations/test/run.sh drives both against the stub Keepiq and a
local release directory, including a tampered binary.

Refs #776
…the CLI

sdk.yml tests the Go, Python and TypeScript libraries on every pull
request that touches sdk/, builds the Python distribution and the npm
tarball as a dry run, and publishes on sdk-py-v* (PyPI trusted
publishing) and sdk-js-v* (npm with provenance); sdk/go/v* tags are the
Go release. cli-release.yml now also runs on sdk/go changes, attaches
SHA256SUMS to each cli-v* release and pushes ghcr.io/conductionnl/keepiq-cli
built from the release binaries. integrations.yml runs the action and
the GitLab template against the stub Keepiq.

Refs #776
…ries-and-ci

Adds docs/client-libraries.md, docs/ci-integrations.md and sdk/README.md,
ticks every task with what was verified here and what is owed, syncs the
two new capabilities into openspec/specs and sets parity rows apps-18
and apps-21 to built.

Closes #776
Comment on lines +82 to +107
needs: build
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- uses: actions/download-artifact@v4
with:
pattern: keepiq-*
merge-multiple: true
path: dist
- name: Write SHA256SUMS
working-directory: dist
run: |
sha256sum keepiq-* > SHA256SUMS
cat SHA256SUMS
test "$(wc -l < SHA256SUMS)" -eq 6
- uses: actions/upload-artifact@v4
with:
name: SHA256SUMS
path: dist/SHA256SUMS
- name: Attach to release
if: startsWith(github.ref, 'refs/tags/cli-v')
uses: softprops/action-gh-release@v2
with:
files: dist/SHA256SUMS

image:
Comment thread sdk/js/src/client.ts
constructor(url: string, private readonly applicationId: string, private readonly privateKeyPem: string, private readonly options: ClientOptions = {}) {
const parsed = new URL(url)
if (!applicationId) throw new Error('application id is required')
this.base = url.replace(/\/+$/, '')
sdk/go/keepiqtest is the in-memory Keepiq machine API the Go library
tests against, exported so the Kubernetes operator, the rotation runner
and the Terraform provider test against the same stub. The library
gains GetByNameIfNoneMatch (an ETag the caller stores, for example in a
resource status), LeaseSupported and RenewLease.

Refs #776
@github-actions

github-actions Bot commented Oct 2, 2026

Copy link
Copy Markdown
Contributor

Quality Report — ConductionNL/keepiq @ 5640c4f

Check PHP Vue Security License Tests
lint ✅
phpcs ✅
phpmd ✅
psalm ✅
phpstan ✅
phpmetrics ✅
eslint ✅
stylelint ✅
build ✅
check-manifest ✅
test-l10n ✅
format ✅
check-l10n-js ✅
check-schema-l10n ✅
composer ✅ ✅ 114/114
npm ✅ ✅ 660/660
app:check-code ⏭️
info.xml ✅
REUSE ✅
lockfile sync ✅
PHPUnit ❌
Newman ❌
Playwright ❌
Hydra gates ✅

Quality workflow — 2026-10-02 10:30 UTC

Download the full PDF report from the workflow artifacts.

@github-actions

github-actions Bot commented Oct 2, 2026

Copy link
Copy Markdown
Contributor

Quality Report — ConductionNL/keepiq @ be1df46

Check PHP Vue Security License Tests
lint ✅
phpcs ✅
phpmd ✅
psalm ✅
phpstan ✅
phpmetrics ✅
eslint ✅
stylelint ✅
build ✅
check-manifest ✅
test-l10n ✅
format ✅
check-l10n-js ✅
check-schema-l10n ✅
composer ✅ ✅ 114/114
npm ✅ ✅ 660/660
app:check-code ⏭️
info.xml ✅
REUSE ✅
lockfile sync ✅
PHPUnit ❌
Newman ✅
Playwright ⏭️ deferred: E2E runs locally and on the promotion path only. This pull request targets development, so the suite is asked once per promotion into beta and main rather than once per push per open pull request. Run it locally with npx playwright test, or from the Actions tab on a branch with no open pull request into development.
Hydra gates ✅

Quality workflow — 2026-10-02 10:37 UTC

Download the full PDF report from the workflow artifacts.

@github-actions

github-actions Bot commented Oct 2, 2026

Copy link
Copy Markdown
Contributor

Quality Report — ConductionNL/keepiq @ 8d62ff7

Check PHP Vue Security License Tests
lint ✅
phpcs ✅
phpmd ✅
psalm ✅
phpstan ✅
phpmetrics ✅
eslint ✅
stylelint ✅
build ✅
check-manifest ✅
test-l10n ✅
format ✅
check-l10n-js ✅
check-schema-l10n ✅
composer ✅ ✅ 114/114
npm ✅ ✅ 660/660
app:check-code ⏭️
info.xml ✅
REUSE ✅
lockfile sync ✅
PHPUnit ❌
Newman ✅
Playwright ⏭️ deferred: E2E runs locally and on the promotion path only. This pull request targets development, so the suite is asked once per promotion into beta and main rather than once per push per open pull request. Run it locally with npx playwright test, or from the Actions tab on a branch with no open pull request into development.
Hydra gates ✅

Quality workflow — 2026-10-02 13:55 UTC

Download the full PDF report from the workflow artifacts.

@rubenvdlinde

Copy link
Copy Markdown
Contributor Author

Local checks: full check on 7bc6982 all 0 (composer check:strict, vitest, Hydra gates, all npm checks). After merging development (40bb9c4): PHPUnit 1664 tests OK, vitest 1300 of 1300, phpmd over lib (three rulesets) 0, phpstan 0, phpcs 0 errors, format, lint, test:l10n and check:l10n-js 0, gate-16 0; go vet and go test green in cli/ and sdk/go (golang:1.22). Merged with a merge commit (not squash) because #922, #926 and #930 are stacked on it.

@rubenvdlinde
rubenvdlinde merged commit 4a506ff into development Oct 2, 2026
60 of 65 checks passed
rubenvdlinde added a commit that referenced this pull request Oct 2, 2026
…o Go 1.25

#914 moved the CLI's client and crypto packages into sdk/go: the agent now
imports github.com/ConductionNL/keepiq/sdk/go/client and /crypto, and the
secret-type test lives in sdk/go/client. sdk/go stays stdlib only on its
own Go 1.22 workflow; only the CLI takes golang.org/x/crypto and
golang.org/x/sys.

As decided for #786: cli/go.mod goes to go 1.25.0 with x/crypto v0.52.0
and x/sys v0.45.0, and the CLI jobs in cli-release.yml and integrations.yml
build with Go 1.25.x. govulncheck stays a blocking step. On go1.25.13: go
vet, go test and govulncheck pass for cli and sdk/go; the Windows build
and the darwin vet pass.
rubenvdlinde added a commit that referenced this pull request Oct 2, 2026
feat: Kubernetes operator for Keepiq application secrets (stacked on #914)
rubenvdlinde added a commit that referenced this pull request Oct 2, 2026
…otation-runner

feat: rotation and sync runner, If-Match write-back and expiresAt (stacked on #914)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants