neatlogs-cli 0.2.1 → 0.2.2

package/docs/execution-secret-custody.md

@@ -0,0 +1,86 @@
+# Execution secrets and the local MCP transport
+
+Secret-producing commands persist a random 256-bit replay key **before dispatch**.
+They reuse it when the same authenticated actor, canonical API host/issuer,
+operation and idempotency key retry the same canonical input. Changed input is a
+local conflict. Access-token refresh does not change the stable actor binding.
+This covers managed credentials, guest links, and service-account tokens.
+
+The default store is the native keyring under
+`com.neatlogs.cli.execution-secrets.v1`, separate from OAuth login credentials.
+A profile that explicitly enabled protected-file login storage uses private
+execution files (0700 directory, 0600 files, no symlink following) instead.
+File keys are published as complete, fsynced immutable records with atomic hard
+links. Concurrent processes return the same winning key. Native creation uses
+an exclusive private lock with atomically published process-owner metadata. A dead
+owner is recovered under a per-inode reaper lock; suspended/live processes are never
+displaced. Contention is bounded to ten seconds. Unparseable legacy lock files remain
+fail-closed because owner liveness cannot be established.
+Once the key was committed, retries bypass the creation lock and reuse it.
+
+Keep the original idempotency key. Recovery reads must find an existing local
+key and never create a replacement. Losing or deleting the local key makes the
+original ciphertext unrecoverable. Retain custody records for at least the
+server's result retention period. This change does not delete keys on success.
+
+## MCP client integration
+
+First authorize a server-registered MCP client with native loopback redirects enabled:
+
+```text
+neatlogs mcp login --issuer https://dev.neatlogs.com --endpoint https://neatlogs-dev-cloud.neatlogs.com/mcp/user --client-id REGISTERED_CLIENT_ID --scope context:read access:write offline_access
+neatlogs mcp proxy --issuer https://dev.neatlogs.com --endpoint https://neatlogs-dev-cloud.neatlogs.com/mcp/user --client-id REGISTERED_CLIENT_ID
+```
+
+Choose the scopes needed by the intended actions. Configure the MCP host to launch
+that proxy command with stdio. Browser sign-in uses PKCE; access and refresh tokens
+use the existing native credential store. Resource/client-specific profiles are
+isolated from ordinary CLI credentials. The proxy refreshes before expiry under a
+cross-process lock. `--allow-file-custody` explicitly permits protected-file storage
+and must also be present when using a file-backed profile. No bearer token belongs
+in the MCP host configuration. Server client registration remains an operator
+prerequisite; these source changes do not establish enabled dev acceptance.
+
+The proxy privately discovers the stable actor and action policy, persists the
+key, and supplies proof in transient HTTP headers. Tool arguments and stored
+server receipts contain no replay key. The server verifies actual key material;
+a model-supplied capability boolean alone is insufficient. Headers are not
+included in the serialized invocation input. The proxy rejects model-supplied
+secret transport headers and prevents reflected replay keys from reaching its
+stdout or custody records.
+
+For secret actions, the model receives a local-custody acknowledgement. It does
+not receive the secret envelope or plaintext. The user retrieves the result in
+a separate terminal:
+
+```text
+neatlogs mcp reveal INVOCATION_UUID --issuer https://dev.neatlogs.com --client-id REGISTERED_CLIENT_ID --endpoint https://neatlogs-dev-cloud.neatlogs.com/mcp/user
+```
+
+This command verifies the current actor and decrypts locally using the existing
+strict credential, guest-link, or service-account envelope validators. It prints
+plaintext intentionally to that terminal. It is never registered as a model
+tool. Guest URL and token audience validation use the verified regional issuer.
+
+`get_action_result` recovers an existing invocation. After receipt expiry,
+`get_saved_action_result` supplies the original operation/input/idempotency key
+and uses the existing custody key without dispatching another mutation. The
+proxy retains the recovered envelope locally for explicit reveal. Missing
+server output, expired retention, missing local keys, revoked access and
+uncertain outcomes remain errors; none authorize a fresh mutation.
+
+`--allow-file-custody` explicitly selects private files for the MCP transport.
+Use the same option for reveal. CLI and MCP share the execution-secret namespace
+and canonical input representation, so a cross-transport retry does not invent
+a second decryption key. Input/receipt metadata and wrapped responses stay in
+the keyring, or the explicitly selected private-file store; ordinary CLI
+configuration and model transcripts contain no raw replay key.
+
+## Qualification
+
+Hosted tests cover immutable file publication across OS processes, restart
+recovery, changed-input rejection, keyring namespace and locks, unsafe files,
+secret-free decrypted server receipts, wrong proof, compatibility of legacy
+read receipts, and proxy lost-response recovery without another execution.
+Run the CLI core suite and backend user-MCP suite remotely. Source tests do not
+establish real client OAuth onboarding, deployment, or live secret acceptance.

package/docs/runtime-detection-reads.md

@@ -0,0 +1,63 @@
+# Runtime detection read reference
+
+The detection read pilot adds `--live` to the existing `api`, `schema list`,
+`schema search`, and `schema show` commands. These additions require the matching
+backend change. This source change does not establish that a deployment or a
+published CLI package includes the pilot.
+
+```bash
+neatlogs --host https://dev.neatlogs.com --project <uuid> schema list --live
+neatlogs --project <uuid> schema search detections --live
+neatlogs --project <uuid> schema show get_api_v1_public_detections --live
+neatlogs --project <uuid> api get_api_v1_public_detections --live --query limit=1
+neatlogs --project <uuid> api get_api_v1_public_detections_detectionId_history --live --param detectionId=<uuid> --query limit=1
+```
+
+Live commands require an OAuth or service-account credential, a selected project,
+`configuration:read`, and `detection:read` permission in that project. Legacy
+public keys and SDK ingestion keys cannot use this catalog.
+
+Each live invocation fetches a fresh authenticated catalog from
+`GET /api/v1/public/action-catalog`. The CLI retains no catalog on disk and reuses
+no catalog between commands. The credential and host resolved for discovery are
+also used for execution within that invocation. A failed or unsupported live
+catalog does not fall back to the embedded contract.
+
+Without `--live`, `schema` remains offline and `api` keeps the release's explicit
+handler registry. Friendly commands keep their current behavior and operation
+IDs. A newly registered compatible backend read can be listed, inspected, and
+executed with the same discovery-capable CLI artifact.
+
+The pilot accepts catalog version `1`, descriptor version `1`, and schema dialect
+`neatlogs-json-schema-v1`. Unknown versions, duplicate operation IDs, unsupported
+schema keywords, unsafe paths, and descriptors outside the detection read policy
+fail before action dispatch. The CLI never downloads or executes action code.
+
+The descriptor contains the method, public path, read effect, accepted credential
+kinds, project requirement, authorization metadata, input/output JSON schemas,
+timeout, and response budget. The backend enforces authorization again when the
+action executes. A catalog entry grants no access by itself.
+
+Requests stay on the configured authenticated origin. The pilot permits only GET
+paths beneath `/api/v1/public/detections` and
+`/api/v1/public/detection-suggestion-runs`. Redirects, absolute URLs, encoded path
+templates, traversal segments, write effects, request bodies, and idempotency keys
+are rejected. Each request has a maximum 10-second timeout. Catalogs are limited
+to 1 MiB and 100 descriptors. Action responses are limited to 2 MiB.
+
+List actions return one bounded page. `--query limit=1` through `limit=100` and
+`--query cursor=<opaque-cursor>` use the backend contract. Live `api` does not
+automatically follow pages. The CLI validates supplied path and query values and
+the complete success response before output. HTTP errors retain the existing
+exit codes and sanitized request-ID diagnostics.
+
+`UNSUPPORTED_CATALOG_VERSION` identifies an unsupported catalog version or
+dialect. `UNSUPPORTED_ACTION_DESCRIPTOR` identifies an unsupported descriptor.
+`UNSUPPORTED_ACTION_SCHEMA` identifies a schema outside the supported subset.
+`ACTION_NOT_AVAILABLE` means that the fresh catalog omits the requested operation.
+A 404 from discovery means that the host lacks that endpoint. A 401 or 403 remains
+an authentication or authorization failure.
+
+The [backend catalog reference](../../backend/docs/public-api/runtime-detection-reads.md)
+defines backend registration and schema compatibility. CLI-Anything is not a
+runtime dependency. This pilot extends the existing TypeScript/Commander CLI.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neatlogs-cli",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Non-interactive CLI for the NeatLogs public API",
   "homepage": "https://github.com/neatlogs/neatlogs-app#readme",
   "license": "MIT",
@@ -42,7 +42,7 @@
   "dependencies": {
     "@github/keytar": "7.10.6",
     "commander": "^14.0.0",
-    "zod": "^4.2.0"
+    "zod": "^4.6.6"
   },
   "devDependencies": {
     "@types/node": "^24.10.1",