@knowttl/technitium-axi 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,74 @@
-# Temporary Holding Version
+# technitium-axi
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+AXI-standard agent-facing CLI for Technitium DNS Server.
+The package provides 46 read operations, strict credential profiles, offline discovery and protected result files.
+Vendor mutations are unavailable.
+
+Install the public npm package globally, then run the `technitium-axi` executable:
+
+```sh
+npm install -g @knowttl/technitium-axi
+technitium-axi --help
+```
+
+Use the Node version pinned in [.node-version](.node-version) and the npm version in the `packageManager` field of [package.json](package.json).
+
+```sh
+npm ci
+npm run build
+npm pack
+npm install --prefix /tmp/technitium-install ./knowttl-technitium-axi-0.1.0.tgz
+/tmp/technitium-install/node_modules/.bin/technitium-axi --help
+/tmp/technitium-install/node_modules/.bin/technitium-axi schema --json
+```
+
+Run native package and harness checks on Linux with `unshare`, `ip` and `openssl` installed:
+
+```sh
+npm run typecheck
+npm run check:generated
+npm run check:journey -- --task B1.01 --paths native --offline
+npm run check:journey -- --task B1.02 --paths native --offline
+```
+
+See [Offline package journeys](docs/offline-checks.md) for isolation, synthetic harness boundaries, cleanup and the full native and Artium checks with their required fixture setup.
+
+Release automation runs `npm run test:release` and installs the packed package for CLI smoke checks with registry access, without a prepared offline cache.
+
+Configure a version 1 config with a named profile containing an HTTPS `origin`, `auth: "token"`, `tokenKind: "api"` and `token: {"env": "MY_TECHNITIUM_TOKEN"}`.
+`schema --json` describes the accepted profile fields.
+SecretRefs also support protected absolute files and explicitly stored credentials.
+Inline secrets and secret flags are refused.
+Ordinary reads never acquire, refresh or store credentials.
+
+```sh
+technitium-axi config path
+technitium-axi config import --input-file /absolute/path/config.json
+technitium-axi profile list
+technitium-axi auth status --profile automation
+technitium-axi status --profile automation
+technitium-axi user session get --profile automation --result-file /absolute/path/session.json
+technitium-axi zone list --profile automation --fields name,type
+technitium-axi zone list --profile automation --full
+technitium-axi settings get --profile automation --result-file /absolute/path/settings.json
+technitium-axi settings backup --profile automation --zones true --result-file /absolute/path/zones.zip
+```
+
+Config selection uses `--config`, then `TECHNITIUM_AXI_CONFIG`, then the platform config directory.
+Profile selection uses `--profile`, `TECHNITIUM_AXI_PROFILE`, a complete environment profile, the configured default, or the sole profile.
+A selected file profile ignores competing environment fields.
+Partial environment profiles fail without borrowing fields.
+The environment profile uses `TECHNITIUM_AXI_ORIGIN`, `TECHNITIUM_AXI_AUTH`, `TECHNITIUM_AXI_TOKEN_KIND`, `TECHNITIUM_AXI_TOKEN` and optional `USERNAME`, `CA_FILE`, `TLS_SERVER_NAME` fields with the same prefix.
+
+`status` and the no-argument view perform one unauthenticated HTTPS status read.
+`user session get` returns a redacted projection; `--result-file` additionally saves the exact confidential JSON in an atomic protected file and reports its path, byte count and SHA-256.
+`caFile` and `tlsServerName` select trust and certificate identity while certificate verification stays enabled.
+Relative `caFile` paths resolve beside the config file that declares them; environment profiles require an absolute CA path.
+Config and CA files must be owned by the current user and not writable by group or others; file SecretRefs and stored credentials must additionally deny all group and other access.
+These reads reject symlinks and redirected paths before consuming the file.
+`doctor` verifies credential protection and performs one bounded session read.
+The generated inventory and each command's `--help` describe the supported read parameters.
+Read [Read contracts and protected results](docs/reads.md) for output bounds, paging, transfer formats and the reviewed archive-entry map.
+Linux file protection is verified natively; native Windows file protection and interruption verification remain PENDING.
+Windows file reads and writes are refused until ownership and ACL verification is available.
+Environment-only profiles and env SecretRefs remain supported when no config file is present.

package/axi-credential.schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/knowttl/technitium-axi/axi-credential.schema.json",
+  "title": "Technitium credential profile",
+  "description": "AXI Credential Standard v2 profile. Secret values must be references.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["origin", "auth", "tokenKind"],
+  "properties": {
+    "origin": { "type": "string", "pattern": "^https://(?:\\[[0-9A-Fa-f:]+\\]|[A-Za-z0-9.-]+)(?::[0-9]{1,5})?$" },
+    "auth": { "const": "token", "type": "string" },
+    "tokenKind": { "type": "string", "enum": ["api", "session", "single-use"] },
+    "token": { "$ref": "#/definitions/secretRef", "x-secret": true, "default": { "env": "TECHNITIUM_AXI_TOKEN" } },
+    "username": { "type": "string", "minLength": 1 },
+    "caFile": { "type": "string", "minLength": 1 },
+    "tlsServerName": { "type": "string", "pattern": "^[A-Za-z0-9.-]+$" },
+    "writes": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["allowWrites", "operations"],
+      "default": { "allowWrites": false, "operations": [] },
+      "properties": {
+        "allowWrites": { "const": false, "type": "boolean" },
+        "operations": { "type": "array", "maxItems": 0, "items": { "type": "string" } }
+      }
+    }
+  },
+  "definitions": {
+    "secretRef": {
+      "oneOf": [
+        { "type": "object", "additionalProperties": false, "required": ["env"], "properties": { "env": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" } } },
+        { "type": "object", "additionalProperties": false, "required": ["file"], "properties": { "file": { "type": "string", "pattern": "^(?:/|[A-Za-z]:[\\\\/]).+" } } },
+        { "type": "object", "additionalProperties": false, "required": ["stored"], "properties": { "stored": { "const": true, "type": "boolean" } } }
+      ]
+    }
+  }
+}

package/bin/technitium-axi.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+
+const args = process.argv.slice(2);
+if (args.length === 1 && ['--version', '-v', '-V'].includes(args[0])) {
+  console.log(JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version);
+} else {
+  const { main } = await import('../dist/cli.js');
+  await main(args);
+}