quoxcli 0.0.0-stage → 0.2.0

package/lib/api/endpoints/engagement.js

@@ -0,0 +1,231 @@
+/**
+ * 'engagement.*' endpoints — QUOX-SECURITY Phase 0 engagement/scope API.
+ * Collector-native (services/collector/server.js:
+ * app.post/get('/api/v1/security/engagements...', requireServiceOrUserAuth(), ...)),
+ * not a proxy. org_id is derived server-side from the authenticated user,
+ * same as the wazuh and quoxagent endpoint fragments, never sent by the CLI.
+ *
+ * NAMING NOTE: the REST path is /api/v1/security/engagements/* but the
+ * endpoint-key prefix here is `engagement.*`, not `security.*` — that
+ * prefix is already taken by services/auth/routes/orgSecurity.js's org
+ * session-policy/ip-allowlist/MFA settings (cli/lib/api/endpoints/security.js),
+ * a genuinely different product concern (org access-control settings, not a
+ * security-testing engagement's scope/policy object). The fragment guard
+ * (test/api/endpoints-fragments.test.js) requires key prefix === filename
+ * minus '.js', so this needed its own file either way.
+ *
+ * See cli/lib/api/endpoints/index.js for the fragment convention.
+ */
+
+export const engagement = {
+  'engagement.create': {
+    method: 'POST',
+    service: 'collector',
+    path: () => `/api/v1/security/engagements`,
+    tags: ['live-write'],
+  },
+  'engagement.list': {
+    method: 'GET',
+    service: 'collector',
+    path: () => `/api/v1/security/engagements`,
+    tags: ['live-safe'],
+  },
+  'engagement.get': {
+    method: 'GET',
+    service: 'collector',
+    path: ({ id }) => `/api/v1/security/engagements/${id}`,
+    tags: ['live-safe'],
+  },
+  // Per-engagement gripe target: which repo a finding filed from this
+  // engagement goes to, and which org's GitHub connector token files it.
+  // lib/securityEngagement.js's setEngagementGripeTarget.
+  'engagement.gripe_target.set': {
+    method: 'PATCH',
+    service: 'collector',
+    path: ({ id }) => `/api/v1/security/engagements/${id}/gripe-target`,
+    tags: ['live-write'],
+  },
+  'engagement.target.create': {
+    method: 'POST',
+    service: 'collector',
+    path: ({ id }) => `/api/v1/security/engagements/${id}/targets`,
+    tags: ['live-write'],
+  },
+  'engagement.target.verify': {
+    method: 'POST',
+    service: 'collector',
+    path: ({ id, targetId }) => `/api/v1/security/engagements/${id}/verify-target/${targetId}`,
+    tags: ['live-write'],
+  },
+  // Phase 1 parity fix: the policy gate and the 3 real capability tools
+  // (lib/securityCapabilityTools.js) were agent-only until this route
+  // existed. Still policy-gated first, still honest about no scan host
+  // being configured, this is the same safety envelope as the agent path.
+  'engagement.check_policy': {
+    method: 'POST',
+    service: 'collector',
+    path: ({ id }) => `/api/v1/security/engagements/${id}/check-policy`,
+    tags: ['live-safe'],
+  },
+  'engagement.capability': {
+    method: 'POST',
+    service: 'collector',
+    path: ({ id, tool }) => `/api/v1/security/engagements/${id}/capability/${tool}`,
+    tags: ['live-write'],
+  },
+  // COVERAGE Phase 2: httpx-based app-port discovery on a bare in-scope host,
+  // finding the ports that actually serve HTTP(S) so a scan hits the real
+  // surface, not only :80/:443. With { add:true } each discovered endpoint is
+  // registered + verified as a url target. lib/securityAppPortDiscovery.js.
+  'engagement.discover_app_ports': {
+    method: 'POST',
+    service: 'collector',
+    path: ({ id }) => `/api/v1/security/engagements/${id}/discover-app-ports`,
+    tags: ['live-write'],
+  },
+  // Quoxcli-parity fix: this catalog existed for the dashboard's Tools tab
+  // but was never CLI-reachable. lib/securityCapabilityTools.js's
+  // getCapabilityToolCatalog().
+  'engagement.capability_tools': {
+    method: 'GET',
+    service: 'collector',
+    path: () => `/api/v1/security/capability-tools`,
+    tags: ['live-safe'],
+  },
+  // Async job model (found live 2026-08-10/11: a real sectest_vuln_scan/
+  // nuclei run outruns the sync route's 30s budget). Same policy gate,
+  // returns job_id immediately, poll engagement.job.get for the result.
+  'engagement.capability.start': {
+    method: 'POST',
+    service: 'collector',
+    path: ({ id, tool }) => `/api/v1/security/engagements/${id}/capability/${tool}/start`,
+    tags: ['live-write'],
+  },
+  'engagement.job.get': {
+    method: 'GET',
+    service: 'collector',
+    path: ({ jobId }) => `/api/v1/security/jobs/${jobId}`,
+    tags: ['live-safe'],
+  },
+  'engagement.jobs.list': {
+    method: 'GET',
+    service: 'collector',
+    path: ({ id }) => `/api/v1/security/engagements/${id}/jobs`,
+    tags: ['live-safe'],
+  },
+  // Findings storage (Phase 1, continued): closes the "no findings storage"
+  // gap. lib/securityFindings.js.
+  'engagement.findings.report': {
+    method: 'POST',
+    service: 'collector',
+    path: ({ id }) => `/api/v1/security/engagements/${id}/findings`,
+    tags: ['live-write'],
+  },
+  'engagement.findings.list': {
+    method: 'GET',
+    service: 'collector',
+    path: ({ id }) => `/api/v1/security/engagements/${id}/findings`,
+    tags: ['live-safe'],
+  },
+  'engagement.findings.verify': {
+    method: 'POST',
+    service: 'collector',
+    path: ({ findingId }) => `/api/v1/security/findings/${findingId}/verify`,
+    tags: ['live-write'],
+  },
+  // Quoxcli-parity fix: marks a finding remediated ("resolved"), e.g. after
+  // the GitHub issue it was filed as was closed. lib/securityFindings.js.
+  'engagement.findings.resolve': {
+    method: 'POST',
+    service: 'collector',
+    path: ({ findingId }) => `/api/v1/security/findings/${findingId}/resolve`,
+    tags: ['live-write'],
+  },
+  // Re-grade a finding's severity after it was reported (quox#601). Governed +
+  // witnessed; a reason is required. lib/securityFindings.js regradeFinding.
+  'engagement.findings.regrade': {
+    method: 'POST',
+    service: 'collector',
+    path: ({ findingId }) => `/api/v1/security/findings/${findingId}/regrade`,
+    tags: ['live-write'],
+  },
+  // Finding -> next-steps pipeline: lib/securityReportActions.js. Raise as
+  // Gripe (GitHub issue), Propose as QuoxPlan (a note on the QUOX-SECURITY
+  // stream), Download PDF (whole engagement report). Email PDF is
+  // explicitly out of scope (needs SMTP).
+  'engagement.report.pdf': {
+    method: 'GET',
+    service: 'collector',
+    path: ({ id }) => `/api/v1/security/engagements/${id}/report.pdf`,
+    tags: ['live-safe'],
+  },
+  'engagement.findings.gripe': {
+    method: 'POST',
+    service: 'collector',
+    path: ({ findingId }) => `/api/v1/security/findings/${findingId}/gripe`,
+    tags: ['live-write'],
+  },
+  'engagement.findings.propose': {
+    method: 'POST',
+    service: 'collector',
+    path: ({ findingId }) => `/api/v1/security/findings/${findingId}/quoxplan`,
+    tags: ['live-write'],
+  },
+  // QUOX-SECURITY-SCHED Phase 4: recurring scan schedules, backed by
+  // lib/securityEngagementSchedules.js (Phase 1 storage) and driven by the
+  // server-side scheduler (lib/securityScanScheduler.js, Phase 2). Cadence is
+  // interval (interval_seconds) or cron (schedule_kind:'cron' + cron_expression,
+  // a 5-field UTC expression); the command builds the body, this fragment is a
+  // pure route descriptor.
+  'engagement.schedule.create': {
+    method: 'POST',
+    service: 'collector',
+    path: ({ id }) => `/api/v1/security/engagements/${id}/schedules`,
+    tags: ['live-write'],
+  },
+  'engagement.schedule.list': {
+    method: 'GET',
+    service: 'collector',
+    path: ({ id }) => `/api/v1/security/engagements/${id}/schedules`,
+    tags: ['live-safe'],
+  },
+  'engagement.schedule.get': {
+    method: 'GET',
+    service: 'collector',
+    path: ({ scheduleId }) => `/api/v1/security/schedules/${scheduleId}`,
+    tags: ['live-safe'],
+  },
+  'engagement.schedule.update': {
+    method: 'PATCH',
+    service: 'collector',
+    path: ({ scheduleId }) => `/api/v1/security/schedules/${scheduleId}`,
+    tags: ['live-write'],
+  },
+  'engagement.schedule.enable': {
+    method: 'POST',
+    service: 'collector',
+    path: ({ scheduleId }) => `/api/v1/security/schedules/${scheduleId}/enable`,
+    tags: ['live-write'],
+  },
+  'engagement.schedule.disable': {
+    method: 'POST',
+    service: 'collector',
+    path: ({ scheduleId }) => `/api/v1/security/schedules/${scheduleId}/disable`,
+    tags: ['live-write'],
+  },
+  'engagement.schedule.delete': {
+    method: 'DELETE',
+    service: 'collector',
+    path: ({ scheduleId }) => `/api/v1/security/schedules/${scheduleId}`,
+    tags: ['live-write'],
+  },
+  // Quoxcli-parity fix: best-effort sync of GitHub issue states onto this
+  // engagement's filed findings (a closed issue auto-resolves its finding).
+  // lib/securityReportActions.js's syncFindingIssueStates.
+  'engagement.sync_issue_states': {
+    method: 'POST',
+    service: 'collector',
+    path: ({ id }) => `/api/v1/security/engagements/${id}/sync-issue-states`,
+    tags: ['live-write'],
+  },
+};

package/lib/api/endpoints/engine.js

@@ -0,0 +1,11 @@
+/**
+ * 'engine.*' endpoints: tasks-service implant stats (QuoxReflect / QuoxLearn / QuoxInsight).
+ * Read-only, org-scoped from the caller's auth (tasks server.js /api/engine/<implant>/stats).
+ * Used by QUOXON /observers for what Quox already records about its own learning.
+ */
+
+export const engine = {
+  'engine.reflect.stats': { method: 'GET', service: 'tasks', path: () => `/api/engine/reflect/stats`, tags: ['live-safe'] },
+  'engine.learn.stats': { method: 'GET', service: 'tasks', path: () => `/api/engine/learn/stats`, tags: ['live-safe'] },
+  'engine.insight.stats': { method: 'GET', service: 'tasks', path: () => `/api/engine/insight/stats`, tags: ['live-safe'] },
+};

package/lib/api/endpoints/entity.js

@@ -0,0 +1,50 @@
+/**
+ * 'entity.*' endpoints — extracted from the former monolithic
+ * cli/lib/api/endpoints.js as part of the per-domain fragment split.
+ * See cli/lib/api/endpoints/index.js for aggregation + the fragment convention.
+ */
+
+export const entity = {
+  'entity.create': {
+    method: 'POST',
+    service: 'memory',
+    path: () => `/api/entity`,
+    tags: ['live-write'],
+  },
+  'entity.get': {
+    method: 'GET',
+    service: 'memory',
+    path: ({ id }) => `/api/entity/${id}`,
+    tags: ['live-safe'],
+  },
+  'entity.delete': {
+    method: 'DELETE',
+    service: 'memory',
+    path: ({ id }) => `/api/entity/${id}`,
+    tags: ['live-write'],
+  },
+  'entity.list': {
+    method: 'GET',
+    service: 'memory',
+    path: () => `/api/entity`,
+    tags: ['live-safe'],
+  },
+  'entity.relation': {
+    method: 'POST',
+    service: 'memory',
+    path: () => `/api/entity/relation`,
+    tags: ['live-write'],
+  },
+  'entity.relation.delete': {
+    method: 'DELETE',
+    service: 'memory',
+    path: ({ id }) => `/api/entity/relation/${id}`,
+    tags: ['live-write'],
+  },
+  'entity.search.list': {
+    method: 'GET',
+    service: 'memory',
+    path: () => `/api/entity/search`,
+    tags: ['live-safe'],
+  },
+};

package/lib/api/endpoints/executions.js

@@ -0,0 +1,32 @@
+/**
+ * 'executions.*' endpoints — extracted from the former monolithic
+ * cli/lib/api/endpoints.js as part of the per-domain fragment split.
+ * See cli/lib/api/endpoints/index.js for aggregation + the fragment convention.
+ *
+ * fleet #465: quoxflow-direct GET routes for execution records
+ * (quoxflow/src/api/routes/executions.ts, mounted at
+ * app.route('/api/executions', ...)). These are the engine's OWN execution
+ * store — a different backend from the auth-service 'runs.*' entries
+ * (runs.js), which quoxflow never writes to. `quox run get`/`run list` use
+ * these as the engine-first read, falling back to 'runs.get'/'runs.list' on
+ * the auth-service model. Same access-path precedent as
+ * 'workflows.activate'/'workflows.applyGet' in workflows.js: org_id is
+ * resolved server-side from the caller's JWT/service-key context
+ * (org-scope.ts, resolveOrgScope), never a URL/query param, so no orgId
+ * path param appears here.
+ */
+
+export const executions = {
+  'executions.get': {
+    method: 'GET',
+    service: 'quoxflow',
+    path: ({ executionId }) => `/api/executions/${executionId}`,
+    tags: ['live-safe'],
+  },
+  'executions.list': {
+    method: 'GET',
+    service: 'quoxflow',
+    path: () => `/api/executions`,
+    tags: ['live-safe'],
+  },
+};

package/lib/api/endpoints/file.js

@@ -0,0 +1,20 @@
+/**
+ * 'file.*' endpoints — extracted from the former monolithic
+ * cli/lib/api/endpoints.js as part of the per-domain fragment split.
+ * See cli/lib/api/endpoints/index.js for aggregation + the fragment convention.
+ */
+
+export const file = {
+  'file.delete': {
+    method: 'DELETE',
+    service: 'files',
+    path: ({ fileId }) => `/file/${fileId}`,
+    tags: ['live-write'],
+  },
+  'file.get': {
+    method: 'GET',
+    service: 'files',
+    path: ({ fileId }) => `/file/${fileId}`,
+    tags: ['live-safe'],
+  },
+};

package/lib/api/endpoints/files.js

@@ -0,0 +1,26 @@
+/**
+ * 'files.*' endpoints — extracted from the former monolithic
+ * cli/lib/api/endpoints.js as part of the per-domain fragment split.
+ * See cli/lib/api/endpoints/index.js for aggregation + the fragment convention.
+ */
+
+export const files = {
+  'files.list': {
+    method: 'GET',
+    service: 'files',
+    path: () => `/list`,
+    tags: ['live-safe'],
+  },
+  'files.stats': {
+    method: 'GET',
+    service: 'files',
+    path: () => `/stats`,
+    tags: ['live-safe'],
+  },
+  'files.upload': {
+    method: 'POST',
+    service: 'files',
+    path: () => `/upload`,
+    tags: ['live-write'],
+  },
+};

package/lib/api/endpoints/github.js

@@ -0,0 +1,21 @@
+/**
+ * 'github.*' endpoints — the collector's governed GitHub proxy
+ * (services/collector/server.js mounts routes/github-proxy.js at /github,
+ * user-authed + github plugin entitlement; credentials resolve from the
+ * org vault server-side, never client-side).
+ *
+ * First fragment added for quox#478 (gripe --yes deterministic fallback).
+ * The full `quox github` command group is tracked separately (quox#566).
+ *
+ * See cli/lib/api/endpoints/index.js for the fragment convention.
+ */
+
+export const github = {
+  'github.issue.create': {
+    method: 'POST',
+    service: 'collector',
+    path: () => `/github/issues`,
+  },
+};
+
+export default github;

package/lib/api/endpoints/governance.js

@@ -0,0 +1,43 @@
+/**
+ * 'governance.*' endpoints — OPGOV quox#582: the governance compiler's
+ * draft-review-arm flow on the collector. Compile is deterministic
+ * (lib/governance/ruleCompiler.js); arming requires a logged-in human, so a
+ * service-key session can compile and list but never arm. Enforcement is
+ * phase 3 and NOT wired yet; nothing here claims otherwise.
+ *
+ * See cli/lib/api/endpoints/index.js for the fragment convention.
+ */
+
+export const governance = {
+  // Pre-existing incident endpoints (from the monolithic endpoints.js split).
+  'governance.incidents.get': {
+    method: 'GET',
+    service: 'collector',
+    path: ({ id }) => `/governance/incidents/${id}`,
+    tags: ['live-safe'],
+  },
+  'governance.incidents.list': {
+    method: 'GET',
+    service: 'collector',
+    path: () => `/governance/incidents`,
+    tags: ['live-safe'],
+  },
+  'governance.policy.compile': {
+    method: 'POST',
+    service: 'collector',
+    path: (p) => `/orgs/${p.orgId}/governance/policies/compile`,
+  },
+  'governance.policy.list': {
+    method: 'GET',
+    service: 'collector',
+    path: (p) => `/orgs/${p.orgId}/governance/policies${p.state ? `?state=${encodeURIComponent(p.state)}` : ''}`,
+    tags: ['live-safe'],
+  },
+  'governance.policy.arm': {
+    method: 'POST',
+    service: 'collector',
+    path: (p) => `/orgs/${p.orgId}/governance/policies/${p.id}/arm`,
+  },
+};
+
+export default governance;

package/lib/api/endpoints/hat.js

@@ -0,0 +1,36 @@
+/**
+ * 'hat.*' endpoints (QUOXHAT #721 b): read-only views of the org's hats.
+ * See cli/lib/api/endpoints/index.js for aggregation + the fragment convention.
+ *
+ * Backend: services/auth/routes/quoxhat.js, mounted at plain `/api` on the
+ * auth service; every route applies requireAuth + requireOrgMembership.
+ * The collector holds only the /internal service-key hat routes, so the
+ * user-facing reads live on auth (same as the dashboard's quoxhatClient).
+ *
+ * - list returns `{ hats: [...hat with definition], settings }`; listing
+ *   also lazily installs/upgrades built-in templates (audited).
+ * - get returns `{ hat, enforcement }`; `hat.revisions` is the history and
+ *   `?revision=n` swaps in that revision's definition (`hat.revision_shown`).
+ */
+
+export const hat = {
+  'hat.list': {
+    method: 'GET',
+    service: 'auth',
+    path: ({ orgId }) => `/api/orgs/${orgId}/quoxhat/hats`,
+    tags: ['live-safe'],
+  },
+  'hat.get': {
+    method: 'GET',
+    service: 'auth',
+    path: ({ orgId, hatId }) => `/api/orgs/${orgId}/quoxhat/hats/${encodeURIComponent(hatId)}`,
+    tags: ['live-safe'],
+  },
+  // Audited reset of an org-edited built-in hat back to its current template
+  // (needs org manage-settings); writes quoxhat.hat.reset_to_template.
+  'hat.reset': {
+    method: 'POST',
+    service: 'auth',
+    path: ({ orgId, hatId }) => `/api/orgs/${orgId}/quoxhat/hats/${encodeURIComponent(hatId)}/reset-to-template`,
+  },
+};

package/lib/api/endpoints/inbox.js

@@ -0,0 +1,32 @@
+/**
+ * 'inbox.*' endpoints — extracted from the former monolithic
+ * cli/lib/api/endpoints.js as part of the per-domain fragment split.
+ * See cli/lib/api/endpoints/index.js for aggregation + the fragment convention.
+ */
+
+export const inbox = {
+  'inbox.get': {
+    method: 'GET',
+    service: 'auth',
+    path: ({ orgId, itemId }) => `/api/orgs/${orgId}/inbox/${itemId}`,
+    tags: ['live-safe'],
+  },
+  'inbox.list': {
+    method: 'GET',
+    service: 'auth',
+    path: ({ orgId }) => `/api/orgs/${orgId}/inbox`,
+    tags: ['live-safe'],
+  },
+  'inbox.respond': {
+    method: 'POST',
+    service: 'auth',
+    path: ({ orgId, itemId }) => `/api/orgs/${orgId}/inbox/${itemId}/respond`,
+    tags: ['live-write'],
+  },
+  'inbox.stats.list': {
+    method: 'GET',
+    service: 'auth',
+    path: ({ orgId }) => `/api/orgs/${orgId}/inbox/stats`,
+    tags: ['live-safe'],
+  },
+};

package/lib/api/endpoints/inboxq.js

@@ -0,0 +1,120 @@
+/**
+ * 'inboxq.*' endpoints — InboxQ (governed email-management plugin), proxied
+ * through the collector (services/collector/server.js:
+ * /api/v1/inboxq/* -> InboxQ routes, org resolved server-side from auth).
+ * No org segment in the URL — same shape as `quoxplan.*`/`quoxbox.*`.
+ *
+ * See cli/lib/api/endpoints/index.js for the fragment convention.
+ */
+
+export const inboxq = {
+  'inboxq.accounts.list': {
+    method: 'GET',
+    service: 'collector',
+    path: () => `/api/v1/inboxq/accounts`,
+    tags: ['live-safe'],
+  },
+  'inboxq.accounts.create': {
+    method: 'POST',
+    service: 'collector',
+    path: () => `/api/v1/inboxq/accounts`,
+    tags: ['live-write'],
+  },
+  'inboxq.accounts.delete': {
+    method: 'DELETE',
+    service: 'collector',
+    path: ({ accountId }) => `/api/v1/inboxq/accounts/${accountId}`,
+    tags: ['live-write'],
+  },
+  'inboxq.messages.get': {
+    method: 'GET',
+    service: 'collector',
+    path: ({ id }) => `/api/v1/inboxq/messages/${encodeURIComponent(id)}`,
+    tags: ['live-safe'],
+  },
+  'inboxq.messages.fetchBody': {
+    method: 'POST',
+    service: 'collector',
+    path: ({ id }) => `/api/v1/inboxq/messages/${encodeURIComponent(id)}/fetch-body`,
+    tags: ['live-write'],
+  },
+  'inboxq.messages.list': {
+    method: 'GET',
+    service: 'collector',
+    path: () => `/api/v1/inboxq/messages`,
+    tags: ['live-safe'],
+  },
+  'inboxq.zones.get': {
+    method: 'GET',
+    service: 'collector',
+    path: () => `/api/v1/inboxq/zones`,
+    tags: ['live-safe'],
+  },
+  // AQ-9E U2: reversible moves
+  'inboxq.moves.recent': {
+    method: 'GET',
+    service: 'collector',
+    path: () => `/api/v1/inboxq/moves/recent`,
+    tags: ['live-safe'],
+  },
+  'inboxq.moves.undo': {
+    method: 'POST',
+    service: 'collector',
+    path: () => `/api/v1/inboxq/moves/undo`,
+    tags: ['live-write'],
+  },
+  'inboxq.sync': {
+    method: 'POST',
+    service: 'collector',
+    path: () => `/api/v1/inboxq/sync`,
+    tags: ['live-write'],
+  },
+  'inboxq.report.generate': {
+    method: 'POST',
+    service: 'collector',
+    path: () => `/api/v1/inboxq/report/generate`,
+    tags: ['live-write'],
+  },
+  'inboxq.report.latest': {
+    method: 'GET',
+    service: 'collector',
+    path: () => `/api/v1/inboxq/report/latest`,
+    tags: ['live-safe'],
+  },
+  'inboxq.watches.list': {
+    method: 'GET',
+    service: 'collector',
+    path: () => `/api/v1/inboxq/watches`,
+    tags: ['live-safe'],
+  },
+  'inboxq.watches.create': {
+    method: 'POST',
+    service: 'collector',
+    path: () => `/api/v1/inboxq/watches`,
+    tags: ['live-write'],
+  },
+  'inboxq.watches.active': {
+    method: 'POST',
+    service: 'collector',
+    path: ({ watchId }) => `/api/v1/inboxq/watches/${watchId}/active`,
+    tags: ['live-write'],
+  },
+  'inboxq.proposals.list': {
+    method: 'GET',
+    service: 'collector',
+    path: () => `/api/v1/inboxq/proposals`,
+    tags: ['live-safe'],
+  },
+  'inboxq.proposals.create': {
+    method: 'POST',
+    service: 'collector',
+    path: () => `/api/v1/inboxq/proposals`,
+    tags: ['live-write'],
+  },
+  'inboxq.proposals.resolve': {
+    method: 'POST',
+    service: 'collector',
+    path: ({ proposalId }) => `/api/v1/inboxq/proposals/${proposalId}/resolve`,
+    tags: ['live-write'],
+  },
+};