@klok-integration/cli 0.7.288 → 0.7.297

package/THIRD-PARTY-NOTICES.md

@@ -838,6 +838,34 @@ The above copyright notice and this permission notice shall be included in all c
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 ```
 
+## jose@6.2.12
+
+Licence: MIT — https://github.com/panva/jose
+
+```
+The MIT License (MIT)
+
+Copyright (c) 2018 Filip Skokan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
 ## json-schema-traverse@1.0.0
 
 Licence: MIT — https://github.com/epoberezkin/json-schema-traverse#readme

package/assets/agents/AGENTS.integration.md

@@ -1,9 +1,9 @@
 ## This repository: integration project
 
-A Klok integration on the Quarkus extension 2.0: one Camel route per class, each extending a framework pattern
-(`KlokOnrampRoute`, `KlokProcessingRoute`, `KlokOfframpRoute`, their `Sync` variants, `KlokRestApi` and
-`KlokRestApiHandlerRoute`, `KlokAsyncTaskWorkerRoute`, `KlokCustomRoute`) and implementing the capabilities it
-needs. Read `klok docs read klok-framework-klok-quarkus-extension` before writing a route.
+A Klok integration on the Quarkus extension 2.0: one Camel route per class (the exceptions are in the platform
+rules), each extending a framework pattern (`KlokOnrampRoute`, `KlokProcessingRoute`, `KlokOfframpRoute`, their
+`Sync` variants, `KlokRestApi` and `KlokRestApiHandlerRoute`, `KlokAsyncTaskWorkerRoute`, `KlokCustomRoute`,
+`KlokRuntimeInstanceRoute`) and implementing the capabilities it needs. Read `klok docs read klok-framework-klok-quarkus-extension` before writing a route.
 
 ### Commands
 

package/assets/agents/knowledge/glossary.md

@@ -14,7 +14,7 @@ it as the source does.
 | DLQ | Dead letter queue: `<topic>_DLQ`, where a message goes after its retries are exhausted |
 | Tenant | An organisation on the platform, and its security boundary; every topic, ODL object and GitLab group belongs to one tenant |
 | Domain | A business area inside a tenant. `common` is shared by the tenant's domains, `public` is open to anyone |
-| Route, route id | One Camel route per Java class. Its id is `<TENANTSHORT><NNN><LEG><seq>_<Description>`, for example `KLK007T1_PublishKlokStandard`; the class name is the id |
+| Route, route id | One Camel route per Java class (except a `KlokRestApi`, one per operation, and a `KlokRuntimeInstanceRoute`, one per instance `<RouteId>#<instanceKey>`). Its id is `<TENANTSHORT><NNN><LEG><seq>_<Description>`, for example `KLK007T1_PublishKlokStandard`; the class name is the id |
 | Leg | The letter in a route id: I ingress (onramp, brings data in), P processing, E egress (offramp, delivers data out), A API, S sub route, T timer |
 | Tenant short name | `TENANTSHORT`, three upper case letters that start every solution and route id of a tenant: the first three consonants of the tenant's name (`KLK` for klok, `DGR` for degerfors), decided by the platform |
 | Solution | The business flow a set of routes implements; its id is the route id's prefix, for example `KLK007`. The id is allocated once, by a merge request in the tenant's `integration-solutions` registry, and never reused; a solution is reserved, active or retired |

package/assets/agents/knowledge/platform-rules.md

@@ -30,6 +30,9 @@ documentation or the dependency catalog can give you.
 
 * One Camel route per Java class. The route id is the class name, the configuration prefix and the solution key:
   `<TENANTSHORT><NNN><LEG><seq>_<Description>` (`KLK002I1_OdlScheduledQuery`, `ACM001E1_FortnoxInvoiceOfframp`).
+  Two exceptions: a `KlokRestApi` gives one Camel route per operation. A `KlokRuntimeInstanceRoute<S>` runs one
+  route class as several Camel routes `<RouteId>#<instanceKey>`, started by `KlokRouteInstanceManager`; its route
+  id, configuration and documentation stay the class's, and the instance key is the log field `klok.route-instance`.
   * `TENANTSHORT`: the tenant's short name, three upper case letters: the first three consonants of the tenant
     slug (`klok` KLK, `degerfors` DGR, `konvoj` KNV), decided by the platform and recorded as `shortname` in
     tenants.yml of `klok/environment/klok-environment-setup`. `NNN`: the solution number, three digits; 900–999

package/assets/agents/skills/klok-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: klok-cli
-description: Which klok command does what on the Klok platform (klok-cli, `@klok/cli`), with the full reference of every command and option in reference.md. Use before running a klok command you have not run in this task, when a task needs the local workspace current (`klok sync pull`), a list of the documentation (`klok docs list`), an answer about the integration landscape (`klok agent ask`), or a check of the solution registry, the deployed fleet, the catalog, a CI job, a deploy manifest, a pin, a bead or a datamodel.
+description: Which klok command does what on the Klok platform (klok-cli, `@klok/cli`), with the full reference of every command and option in reference.md. Use before running a klok command you have not run in this task, when a task needs the local workspace current (`klok sync pull`), a list of the documentation (`klok docs list`), an answer about the integration landscape (`klok agent ask`), or a check of the solution registry, the deployed fleet, the catalog, a CI job, a deploy manifest, a pin, a bead or a datamodel, or a file transfer flow's sealed secrets and its write to the ODL.
 ---
 
 # The klok command line
@@ -34,6 +34,7 @@ CLI version, generated from the program itself; when it is missing (an installer
 | the repository, root element and namespace a datamodel's class and name give | `klok datamodel names` |
 | an XSD checked the way the datamodel pipeline checks it | `klok datamodel validate` |
 | this repository's `klok-docs/` checked before the merge request | `klok docs build`, `klok docs verify` |
+| a sealing key for a tenant's klok-file-transfer, a secret sealed for a file flow, or flows written to the ODL from Git | `klok file-transfer keygen`, `seal`, `apply --dry-run` (then without) |
 
 ## The workspace
 
@@ -56,6 +57,18 @@ followed to the new one, and stderr says `<old-id> moved to <new-id>`: use the n
 solution registry, the integration context and the documentation you may read, and answers with links; it is the
 quickest way to find which project, leg or topic handles something.
 
+## File transfer (KLK017)
+
+A file flow (`KlokFileFlowV1`) lives in the tenant's ODL, and its passwords, private keys and passphrases only as
+sealed values that the tenant's klok-file-transfer instance alone can open, for one flow and one field. `klok
+file-transfer seal --flow <id> --field <path>` reads the secret from stdin and prints the sealed value; the person who
+holds the secret runs it, never an agent, and a secret never goes into a command line, a file or a message. `klok
+file-transfer apply <dir>` writes the flow files of a repository to the ODL with `managedBy: git:<repo>@<sha>`: it
+refuses a plain secret, checks every flow against the released datamodel and writes nothing until all are valid; run
+it with `--dry-run` first. `klok file-transfer keygen` writes a new private key to a file and prints the `vault kv
+patch` command: a person writes Vault, an agent hands the command over. The operator guide is klok-file-transfer's
+*Usage* and *Operations* pages (`klok docs read klok-integration-klok-file-transfer`).
+
 ## klok.dev
 
 The CLI is meant to do everything klok.dev does, as the person, but only part of the portal has its command yet

package/assets/agents/skills/klok-cli/reference.md

@@ -119,7 +119,7 @@ Print one effective configuration value; secrets show as **** unless --reveal
 klok config set [options] <key> [value]
 ```
 
-Set a value. Keys: agentUrl, tenant, klokDevUrl, keycloakIssuer, keycloakClientId, protocol, domain, gitUrl, workspace, klokerBasePath, klokerUrl, klokerModel, summaryLanguage, klokApiKey. Leave out the value of a secret (klokApiKey) to type it at a prompt that shows * for each character, or pipe it in, so it stays off the screen and out of the shell history
+Set a value. Keys: agentUrl, tenant, klokDevUrl, keycloakIssuer, keycloakClientId, protocol, domain, gitUrl, workspace, klokerBasePath, klokerUrl, klokerModel, summaryLanguage, klokApiKey, odlUrl. Leave out the value of a secret (klokApiKey) to type it at a prompt that shows * for each character, or pipe it in, so it stays off the screen and out of the shell history
 
 | Argument | Description |
 |---|---|
@@ -768,6 +768,95 @@ Build the znai project and upload it under this project’s doc id. When klok-do
 | `-n, --dry-run` | Resolve what would be published and build it with znai, upload nothing; for a retired project, say what would be unpublished |
 | `--no-build` | With --dry-run: only resolve the plan, do not run znai |
 
+## klok file-transfer
+
+```
+klok file-transfer [options] [command]
+```
+
+KLK017 File Transfer: sealing keys, sealed secrets, and flows written to the ODL from Git
+
+### klok file-transfer keygen
+
+```
+klok file-transfer keygen [options]
+```
+
+Make a new sealing key pair (RSA 3072, private JWK) for a tenant's klok-file-transfer instance
+
+| Option | Description |
+|---|---|
+| `--out <file>` | Write a new JWK set holding only this key to <file> (mode 0600; never overwritten) |
+| `--add-to <file>` | Append the key to the JWK set in <file>, the set as Vault holds it (rotation) |
+| `--kid <kid>` | Key id, default klk-ft-<yyyy-mm> |
+
+```
+The private key never goes to a log: without --out or --add-to it is printed on stdout only, and only on a terminal.
+klok-cli never writes Vault. It prints the vault kv patch command for a person to run with the file, which then
+holds the whole set: the old keys stay, so what was sealed with them still opens, and the last key is CURRENT.
+
+  klok file-transfer keygen --tenant klok --out sealing-keys.json                 # the first key
+  klok file-transfer keygen --tenant klok --add-to sealing-keys.json              # rotation, see klok-file-transfer's Operations page
+```
+
+### klok file-transfer seal
+
+```
+klok file-transfer seal [options]
+```
+
+Seal a password, private key or passphrase for one field of one flow; prints the KlokSealedValueV1 JSON
+
+| Option | Description |
+|---|---|
+| `--flow <id>` | The flow id the value belongs to |
+| `--field <path>` | source.endpoint.<f> or destinations.<name>.endpoint.<f>; <f> is password, privateKey or passphrase |
+| `--key <file>` | Seal offline with this public JWK (or the last key of a JWK set) instead of the ODL's CURRENT key |
+| `--kid <kid>` | Seal with this key instead of the CURRENT one |
+| `--set-by <who>` | Who set the value (setBy), default the logged in user |
+| `--token <token>` | GitLab token to find the tenant's ODL in tenants.yml (default: KLOK_GIT_APIKEY, GITLAB_TOKEN, config klokApiKey) |
+
+```
+The value is read from stdin: typed without echo on a terminal, or piped (a private key file). It is never an
+argument, never printed and never logged. The output goes into the flow JSON at the field's place:
+
+  klok file-transfer seal --tenant klok --flow payroll-to-bank --field destinations.bank.endpoint.password
+  klok file-transfer seal --tenant klok --flow payroll-to-bank --field source.endpoint.privateKey < ~/keys/payroll_ed25519
+
+A sealed value opens only in the tenant's klok-file-transfer instance, only for this flow and this field. Renaming the
+flow or the destination means sealing again.
+```
+
+### klok file-transfer apply
+
+```
+klok file-transfer apply [options] <dir|file>
+```
+
+Write the KlokFileFlowV1 files of a directory (or one file) to the tenant's ODL, managed by Git
+
+| Argument | Description |
+|---|---|
+| `<dir|file>` | A folder of *.json flow files (searched recursively) or one flow file |
+
+| Option | Description |
+|---|---|
+| `--dry-run` | Check everything and show what would be created or changed; write nothing |
+| `--schema <file>` | KlokFileFlowV1.avsc to validate against instead of the released datamodel |
+| `--token <token>` | GitLab token to read tenants.yml and the datamodel's package (default: KLOK_GIT_APIKEY, GITLAB_TOKEN, config klokApiKey, CI_JOB_TOKEN) |
+
+```
+Every file holds one flow; its "id" is the object id. Before anything is written, every flow is checked against
+the released datamodel klok-file-transfer-v1, and every password, privateKey and passphrase must be a sealed value
+that the tenant's instance opens for that flow and field: a plain password is refused. Each flow is written with
+managedBy git:<repo>@<sha> (the CI project and commit, or the checkout's origin and HEAD), so the files must be
+committed. A flow changed in the ODL since it was read is not overwritten. Flows that are not in the files are
+left alone: apply never deletes.
+
+  klok file-transfer apply --tenant klok flows/ --dry-run
+  klok file-transfer apply --tenant klok flows/
+```
+
 ## klok fleet
 
 ```