mirror of
https://github.com/ruvnet/RuView.git
synced 2026-09-01 13:07:25 +00:00
feat(spaces): add spatial memory and governed actions (#1650)
This commit is contained in:
rUv
@@ -34,8 +34,14 @@ metaharness:
|
||||
```bash
|
||||
wifi-densepose whoami
|
||||
npx @ruvnet/ruview spaces
|
||||
npx @ruvnet/ruview spaces --resource sites
|
||||
npx @ruvnet/ruview spaces --resource events --limit 25
|
||||
```
|
||||
|
||||
The versioned collections are `sites`, `buildings`, `floors`, `spaces`,
|
||||
`zones`, `entities`, `events`, and `alerts`. Continue a page with the returned
|
||||
opaque `nextCursor`; do not decode or reuse a cursor for another collection.
|
||||
|
||||
Use `--credentials-path <private-file>` only from the human-invoked CLI when a
|
||||
non-default credential store is intentional. Never put a bearer token or API
|
||||
key on the command line.
|
||||
@@ -54,7 +60,7 @@ npx @ruvnet/ruview mcp start
|
||||
```
|
||||
|
||||
MCP calls cannot choose a credential path and the tool schema has no token or
|
||||
API-key or base-URL field. The API origin is fixed to
|
||||
API-key, workspace override, or base-URL field. The API origin is fixed to
|
||||
`https://api.cognitum.one`, the adapter requires an installed
|
||||
`wifi-densepose` binary, and the child environment excludes
|
||||
`COGNITUM_SPACES_API`, so this
|
||||
@@ -66,5 +72,6 @@ API-key path.
|
||||
An empty `data` list can be a valid authenticated tenant result. It proves the
|
||||
read path and isolation behavior, not sensing quality. Every accepted response
|
||||
must declare `HomeCore Edge` as authoritative and carry the complete prohibited
|
||||
field list. Any malformed, oversized, non-semantic, or raw-field response fails
|
||||
closed.
|
||||
field list. Parent lineage, schema version, anonymous person/track identity,
|
||||
event/alert fields, confidence, and cursor bounds are independently checked.
|
||||
Any malformed, oversized, non-semantic, or raw-field response fails closed.
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
"generator": "RuView metaharness provenance v2",
|
||||
"template": "vertical:ruview",
|
||||
"name": "@ruvnet/ruview",
|
||||
"version": "0.4.0",
|
||||
"version": "0.5.0",
|
||||
"hosts": [
|
||||
"claude-code",
|
||||
"codex"
|
||||
@@ -12,7 +12,7 @@
|
||||
"files": {
|
||||
".claude/settings.json": "57d03e8995363bd120fb6d515702967afd0bd557797051301ff8f8156c845824",
|
||||
".claude/skills/calibrate-room/SKILL.md": "4b29c7c331f47acad3c0f51b3d3d8f5b5573e316e081bae71dbe21a47fa95240",
|
||||
".claude/skills/cognitum-spaces/SKILL.md": "7f59877f86dacb8c71d8aaf757a5cfcf534ba323488da1761a1e965f74248805",
|
||||
".claude/skills/cognitum-spaces/SKILL.md": "96ae42cc72ad31dbb2f34d59e874c4d15f2e55fc969cd1f610dc1b9a4138840e",
|
||||
".claude/skills/onboard/SKILL.md": "97ee71f0aa985cfc03bb8e764789bb55c4f9fd5dae10a116c1071eab85b5893f",
|
||||
".claude/skills/provision-node/SKILL.md": "5f73823794ed5f0b25c102aa8b1bf2dd534a1ec468173d8330c2af0ca24f239c",
|
||||
".claude/skills/train-pose/SKILL.md": "92aebd4423470eb10eabaee642ec3493284d98b7ae9785e0f34378c709746e65",
|
||||
@@ -20,10 +20,10 @@
|
||||
".harness/claims.json": "9544cee8012328eb26856a9fff38d80a73f09e48a2da7537f6c3695521b0fd54",
|
||||
".harness/mcp-policy.json": "749e9f24bde85921a45b91bf6fa4ab5605675af769c04c53fe69129019662d3e",
|
||||
".mcp/servers.json": "fec6075400f8350d8075beac8306690355c4b015425bfd0e5f52966234e9d66f",
|
||||
"CLAUDE.md": "61a96113d7ccfe534f7dfc7c59afd876faf0b732bca4f618aa3dcea07bd0f839",
|
||||
"CLAUDE.md": "46d5514f4cbf4d94f683f76aa6d50a3dce2ec5a95fd87b9154ed4752f5ea0e16",
|
||||
"LICENSE": "631f94984f626818d42ecf717aa6e8e0afd4f9f355ca706bd2effafbd1416d06",
|
||||
"README.md": "e9593d9ebd888eef065fd37e13daf17cf3d8e19f754d5fe11541f27f10db48db",
|
||||
"bin/cli.js": "92700671c878bd4989dfcc23e3e8325ed3bb9bcc9b707fcd9330f33b2d5a3c39",
|
||||
"README.md": "ce716f07b4b93d5b86285a46cc7be1c6ff48d95ee12ac73518dbf2fb7b61d82e",
|
||||
"bin/cli.js": "0c96bf65a189732a35760c88a3d441a5bd6ce53abbd3bfaa73141665825e1be1",
|
||||
"brain/corpus/core.jsonl": "c0fb7b079ded157059b91601361429944697dae3cc42abc00dfe1a680986b0f4",
|
||||
"flywheel/evaluations.json": "ac4ff1f897a2444870cd2b8ae8aee8b1578e61467aeca4db57893f41be98a572",
|
||||
"flywheel/fixture.mjs": "de71be88753d0da4695d91011b54380c994a018986fafba36cb13739307a9bce",
|
||||
@@ -31,19 +31,19 @@
|
||||
"flywheel/genome.json": "75db44a3cab70d9459fc8c07863f640ac1214bfaa243483939e1506d63f51214",
|
||||
"flywheel/replay.mjs": "0670ca0b03701f4afe0b4bca8a3d58d481676b61a94a5b98c6a425aefb1159ab",
|
||||
"flywheel/run.mjs": "6d4f97db16900c45367b6538848cbe1915af999e663720dfc51f2bb1698f1cd0",
|
||||
"package.json": "f30fa3704a63ca45b8b873294d3ce56603c18361cef16f21c0615cc74567c232",
|
||||
"package.json": "e508476278467cbe63e836d2b42f24649393fb59ce4fe40925d4418da4e79acc",
|
||||
"scripts/sync-skills.mjs": "43715dab61e204dc91bbd61755810e8fdb2f66e2b0c0bd791b4bf48a2e293565",
|
||||
"scripts/update-manifest.mjs": "8f56764b8f70aed55da0c7e2417ae875b0d58d781d839b6db7f115f08af61e6b",
|
||||
"scripts/verify-manifest.mjs": "6491a221762efcfeb3e749ecab243b204f17fd5bc871f3d4025597f31b8f0f10",
|
||||
"skills/calibrate-room.md": "4b29c7c331f47acad3c0f51b3d3d8f5b5573e316e081bae71dbe21a47fa95240",
|
||||
"skills/cognitum-spaces.md": "7f59877f86dacb8c71d8aaf757a5cfcf534ba323488da1761a1e965f74248805",
|
||||
"skills/cognitum-spaces.md": "96ae42cc72ad31dbb2f34d59e874c4d15f2e55fc969cd1f610dc1b9a4138840e",
|
||||
"skills/onboard.md": "97ee71f0aa985cfc03bb8e764789bb55c4f9fd5dae10a116c1071eab85b5893f",
|
||||
"skills/provision-node.md": "5f73823794ed5f0b25c102aa8b1bf2dd534a1ec468173d8330c2af0ca24f239c",
|
||||
"skills/train-pose.md": "92aebd4423470eb10eabaee642ec3493284d98b7ae9785e0f34378c709746e65",
|
||||
"skills/verify.md": "2d38d240e9810a7827e2ebd3717dc0f85c646cc92e46c3812fe77c5b9eb40b76",
|
||||
"src/brain.js": "0f16a75aea943acdacc430ff11d5df7ecdec9cca2ab497795ff6f33eaebdfab6",
|
||||
"src/guardrails.js": "aacc8fa6088f7f1ccea3a0b02171a5c516b95d3416ee3ba87add3879a1d6aaad",
|
||||
"src/guidance.js": "599fb7317c6ab2166e5d4eb89954fa303b9d29fae361a6f4d01c0eff7e7e220d",
|
||||
"src/guidance.js": "bc9a8c1ffcfd378110e56e5d0a3559806fbbeb65523a895fc685c3ae61306219",
|
||||
"src/hosts/claude-code.js": "2212bc39b49822018800dfe33a471e56bbb4c5233d716bfa7aa4fff77aa23edb",
|
||||
"src/hosts/codex.js": "d41ecd132ce2db7b47aad9cebbc020d70e6810d48c3554858d099ff2e8f6608b",
|
||||
"src/hosts/index.js": "ab276c41ab722bcdf72c2d1649cecbb760ae05c41c1372aae4c2447aa7c11539",
|
||||
@@ -52,10 +52,10 @@
|
||||
"src/process-runner.js": "49533b038044dfb8bc76ed01c030d06a9856ead0836157fb693e2a7d40f786d6",
|
||||
"src/redact.js": "ebf1afff46341078706b0401838c53db043603586e280d51ece5cf1feba35189",
|
||||
"src/repo-trust.js": "06e2a94d7113ed936f208a12b7fcc785801c215a3e2c5e7418f6238d991a289c",
|
||||
"src/spaces.js": "d102792339d4f4c0cc4cf344a9c18f1aa660749d742120c6f2a88ddeb78b343a",
|
||||
"src/tools.js": "f5ce697b649721966afcb43dce86ff32350feae5bf7b561722291f143d8c3550"
|
||||
"src/spaces.js": "45ef786537cb2a446db5e926e5a1c10b73639d2767dec84611f914f78d4325eb",
|
||||
"src/tools.js": "55960c9a677661763e0317fd54ccc787c2edb39c87371c7fbc40cd55f0761c04"
|
||||
},
|
||||
"filesDigest": "8861774e126ba3c06318bb7379726d98841cb42c5f660e91bd62288f7ca61f8b",
|
||||
"filesDigest": "9df582d6d4cbf378999a55d7561fc14f795145354258126b12da894433258047",
|
||||
"brainDigest": "c0fb7b079ded157059b91601361429944697dae3cc42abc00dfe1a680986b0f4",
|
||||
"gateFingerprint": "6e53c784eee38310188948fc75fb49e6b4ebc04e247d01b903fa8c8a92d67bdd",
|
||||
"developmentPins": {
|
||||
|
||||
@@ -1 +1 @@
|
||||
e80b6abc4b8a0f99a154a470c4919ffc3886a715ec7f327f5f2f991bc7bf4293 manifest.json
|
||||
45df19e5f93f14a1365ca9341a0838fbe79231ecfbac6911e24e24d3530107ee manifest.json
|
||||
|
||||
@@ -26,10 +26,12 @@ navigation evidence, not authority. All tools fail closed. Mutating/hardware
|
||||
tools (`node_flash`) require explicit confirmation and are Windows/ESP-IDF
|
||||
gated.
|
||||
|
||||
`ruview_spaces_list` is an OAuth-only external read. MCP calls require the
|
||||
`ruview_spaces_list` is an OAuth-only external read for the eight versioned
|
||||
hierarchy/event/alert collections. MCP calls require the
|
||||
`credential-use` grant, cannot select a credential path or API origin, and may
|
||||
rotate the local refresh credential. It requires an installed binary and never
|
||||
runs Cargo from an auto-detected checkout. It grants no write or action authority.
|
||||
runs Cargo from an auto-detected checkout. Cursors are opaque and collection-
|
||||
bound. It grants no write or action authority.
|
||||
|
||||
## Skills
|
||||
|
||||
|
||||
@@ -17,7 +17,8 @@ npx @ruvnet/ruview claim-check --file REPORT.md # the honesty guardrail (non-z
|
||||
npx @ruvnet/ruview verify # run the deterministic proof (VERDICT: PASS)
|
||||
npx @ruvnet/ruview doctor # self-check (tools, adapters, local CLIs)
|
||||
npx @ruvnet/ruview guidance --topic homecore --query "Wasmtime plugins"
|
||||
npx @ruvnet/ruview spaces # OAuth-only Cognitum Spaces read
|
||||
npx @ruvnet/ruview spaces --resource spaces
|
||||
npx @ruvnet/ruview spaces --resource events --limit 25
|
||||
npx @ruvnet/ruview --help
|
||||
```
|
||||
|
||||
@@ -39,7 +40,7 @@ Exposed both as CLI verbs and as an MCP server (`npx @ruvnet/ruview mcp start`):
|
||||
| `ruview_calibrate` | ADR-151 room pipeline (baseline→enroll→train-room→room-watch) |
|
||||
| `ruview_node_flash` | Build+flash firmware (Windows/ESP-IDF; mutating, guarded) |
|
||||
| `ruview_guidance` | Source-cited code map, capability maturity, validation commands, and limitations |
|
||||
| `ruview_spaces_list` | OAuth-only, tenant/workspace Cognitum Spaces projection (guarded over MCP) |
|
||||
| `ruview_spaces_list` | OAuth-only paging for sites/buildings/floors/spaces/zones/entities/events/alerts (guarded over MCP) |
|
||||
| `ruview_memory_search` | Search the reviewed, source-cited contributor brain |
|
||||
|
||||
Every tool is **fail-closed**: missing repo / python / binary / port → an honest
|
||||
@@ -54,6 +55,8 @@ validated client through the metaharness:
|
||||
wifi-densepose login --spaces
|
||||
wifi-densepose whoami
|
||||
npx @ruvnet/ruview spaces
|
||||
npx @ruvnet/ruview spaces --resource sites --limit 50
|
||||
npx @ruvnet/ruview spaces --resource events --cursor '<opaque-next-cursor>'
|
||||
```
|
||||
|
||||
The metaharness never accepts a bearer token or API key and removes
|
||||
@@ -62,9 +65,11 @@ silently fall back to the compatibility API-key path. The API origin is fixed
|
||||
to `https://api.cognitum.one`, and the credentialed adapter requires an
|
||||
installed `wifi-densepose` binary rather than running Cargo build scripts from
|
||||
an auto-detected checkout. It returns only the bounded P2/P3 semantic
|
||||
projection; an empty list is a valid authenticated result, not sensing-quality
|
||||
evidence. An expired session may rotate the stored refresh credential before
|
||||
the read completes.
|
||||
projection. `--resource` selects one of `sites`, `buildings`, `floors`,
|
||||
`spaces`, `zones`, `entities`, `events`, or `alerts`; `--limit` is 1–100 and
|
||||
`--cursor` is the opaque value from the prior page. An empty list is a valid
|
||||
authenticated result, not sensing-quality evidence. An expired session may
|
||||
rotate the stored refresh credential before the read completes.
|
||||
|
||||
MCP use is denied unless the server operator starts it with
|
||||
`RUVIEW_MCP_GRANTS=credential-use`. Set `RUVIEW_CREDENTIALS_PATH` in the MCP
|
||||
|
||||
@@ -71,7 +71,7 @@ Operator tools:
|
||||
monitor --port COM8 [--seconds 12] assert CSI is flowing on a node
|
||||
flash --port COM8 --variant s3-8mb [--confirm] build+flash firmware (Windows/ESP-IDF)
|
||||
guidance [--topic homecore] [--query "Wasmtime"] source-cited code/capability map
|
||||
spaces [--credentials-path <file>] list the OAuth-bound Cognitum Spaces projection
|
||||
spaces [--resource sites|...|alerts] [--limit 50] page OAuth-bound Cognitum spatial resources
|
||||
|
||||
Harness:
|
||||
doctor verify tools, adapters, and local CLI discovery
|
||||
@@ -130,6 +130,7 @@ export async function run(args) {
|
||||
if (cmd === 'spaces') {
|
||||
if (flags['credentials-path'] !== undefined) toolArgs.credentials_path = flags['credentials-path'];
|
||||
delete toolArgs['credentials-path'];
|
||||
if (flags.limit !== undefined) toolArgs.limit = Number(flags.limit);
|
||||
}
|
||||
const res = await runTool(VERB_TO_TOOL[cmd], toolArgs, { source: 'cli' });
|
||||
pjson(res);
|
||||
|
||||
4
harness/ruview/package-lock.json
generated
4
harness/ruview/package-lock.json
generated
@@ -1,12 +1,12 @@
|
||||
{
|
||||
"name": "@ruvnet/ruview",
|
||||
"version": "0.4.0",
|
||||
"version": "0.5.0",
|
||||
"lockfileVersion": 3,
|
||||
"requires": true,
|
||||
"packages": {
|
||||
"": {
|
||||
"name": "@ruvnet/ruview",
|
||||
"version": "0.4.0",
|
||||
"version": "0.5.0",
|
||||
"license": "MIT",
|
||||
"bin": {
|
||||
"ruview": "bin/cli.js"
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "@ruvnet/ruview",
|
||||
"version": "0.4.0",
|
||||
"version": "0.5.0",
|
||||
"description": "RuView WiFi-sensing operator harness — onboard, calibrate, verify, enforce evidence guardrails, and read Cognitum Spaces through explicitly granted OAuth.",
|
||||
"type": "module",
|
||||
"bin": {
|
||||
|
||||
@@ -34,8 +34,14 @@ metaharness:
|
||||
```bash
|
||||
wifi-densepose whoami
|
||||
npx @ruvnet/ruview spaces
|
||||
npx @ruvnet/ruview spaces --resource sites
|
||||
npx @ruvnet/ruview spaces --resource events --limit 25
|
||||
```
|
||||
|
||||
The versioned collections are `sites`, `buildings`, `floors`, `spaces`,
|
||||
`zones`, `entities`, `events`, and `alerts`. Continue a page with the returned
|
||||
opaque `nextCursor`; do not decode or reuse a cursor for another collection.
|
||||
|
||||
Use `--credentials-path <private-file>` only from the human-invoked CLI when a
|
||||
non-default credential store is intentional. Never put a bearer token or API
|
||||
key on the command line.
|
||||
@@ -54,7 +60,7 @@ npx @ruvnet/ruview mcp start
|
||||
```
|
||||
|
||||
MCP calls cannot choose a credential path and the tool schema has no token or
|
||||
API-key or base-URL field. The API origin is fixed to
|
||||
API-key, workspace override, or base-URL field. The API origin is fixed to
|
||||
`https://api.cognitum.one`, the adapter requires an installed
|
||||
`wifi-densepose` binary, and the child environment excludes
|
||||
`COGNITUM_SPACES_API`, so this
|
||||
@@ -66,5 +72,6 @@ API-key path.
|
||||
An empty `data` list can be a valid authenticated tenant result. It proves the
|
||||
read path and isolation behavior, not sensing quality. Every accepted response
|
||||
must declare `HomeCore Edge` as authoritative and carry the complete prohibited
|
||||
field list. Any malformed, oversized, non-semantic, or raw-field response fails
|
||||
closed.
|
||||
field list. Parent lineage, schema version, anonymous person/track identity,
|
||||
event/alert fields, confidence, and cursor bounds are independently checked.
|
||||
Any malformed, oversized, non-semantic, or raw-field response fails closed.
|
||||
|
||||
@@ -232,23 +232,26 @@ const CAPABILITIES = Object.freeze([
|
||||
id: 'cognitum-spaces-oauth',
|
||||
name: 'Cognitum Spaces OAuth projection',
|
||||
topics: ['integrations', 'deployment', 'community'],
|
||||
status: 'implemented-read-only',
|
||||
evidence: 'PRODUCTION',
|
||||
summary: 'RuView explicitly activates spaces:read through Cognitum Authorization Code + PKCE, and the contributor metaharness exposes the validated tenant/workspace projection through an OAuth-only CLI/MCP adapter.',
|
||||
status: 'implemented-read-only-staged',
|
||||
evidence: 'MIXED',
|
||||
summary: 'The legacy Spaces OAuth read is live. The feature branch extends the same read-only PKCE authority across the versioned site/building/floor/space/zone/entity/event/alert collections with bounded pagination and independent metaharness validation.',
|
||||
sources: [
|
||||
'docs/adr/ADR-325-cognitum-spaces-activation-and-governed-spatial-exchange.md',
|
||||
'v2/crates/wifi-densepose-cli/src/spaces.rs',
|
||||
'harness/ruview/src/spaces.js',
|
||||
'docs/adr/ADR-326-tenant-scoped-ruvector-spatial-memory.md',
|
||||
'docs/adr/ADR-327-governed-action-intents-and-witness-receipts.md',
|
||||
],
|
||||
validation: [
|
||||
'cd harness/ruview && node --test test/spaces.test.mjs test/policy.test.mjs',
|
||||
'wifi-densepose login --spaces && node harness/ruview/bin/cli.js spaces',
|
||||
'wifi-densepose login --spaces && node harness/ruview/bin/cli.js spaces --resource events',
|
||||
],
|
||||
limitations: [
|
||||
'The projection is read-only and grants no write, pairing, command, policy-approval, or actuator authority.',
|
||||
'MCP requires the credential-use grant; bearer tokens and API keys are never accepted as tool arguments.',
|
||||
'OAuth refresh may rotate the local credential file before a read returns.',
|
||||
'The deployed slice exposes spaces only; the broader hierarchy, events, alerts, persistent spatial memory, and governed actions remain follow-up work.',
|
||||
'Production evidence covers the legacy flat Spaces read. Versioned collections, spatial memory, and governed actions remain staged until workflow deployment/readback.',
|
||||
'Persistent memory is local tenant/workspace state and governed actions expose authorization receipts only; neither expands OAuth authority.',
|
||||
],
|
||||
},
|
||||
{
|
||||
|
||||
@@ -12,8 +12,16 @@ import { redact } from './redact.js';
|
||||
const DEFAULT_BASE_URL = 'https://api.cognitum.one';
|
||||
const MAX_CLI_JSON_BYTES = 2 * 1024 * 1024;
|
||||
const MAX_JSON_DEPTH = 16;
|
||||
const MAX_JSON_NODES = 10_000;
|
||||
const MAX_ARRAY_ITEMS = 1000;
|
||||
const MAX_OBJECT_KEYS = 128;
|
||||
const MAX_STRING_BYTES = 4096;
|
||||
const MAX_SPACES = 100;
|
||||
const MAX_RESOURCES = 100;
|
||||
const ID_RE = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,119}$/;
|
||||
const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
|
||||
export const SPATIAL_RESOURCE_KINDS = Object.freeze([
|
||||
'sites', 'buildings', 'floors', 'spaces', 'zones', 'entities', 'events', 'alerts',
|
||||
]);
|
||||
const REQUIRED_EXCLUSIONS = Object.freeze([
|
||||
'raw_csi',
|
||||
'cir',
|
||||
@@ -23,7 +31,13 @@ const REQUIRED_EXCLUSIONS = Object.freeze([
|
||||
'vital_waveforms',
|
||||
'identity_observations',
|
||||
]);
|
||||
const FORBIDDEN_FIELDS = new Set(REQUIRED_EXCLUSIONS.map(normalizeField));
|
||||
const FORBIDDEN_FIELDS = new Set([
|
||||
...REQUIRED_EXCLUSIONS.map(normalizeField),
|
||||
'csi', 'channelstateinformation', 'rawcir', 'channelimpulseresponse',
|
||||
'rftensor', 'rftensors', 'packetcapture', 'packetcaptures', 'pcap', 'recording', 'recordings', 'audiorecording',
|
||||
'videorecording', 'poseframe', 'skeleton', 'keypoints', 'vitalwaveform',
|
||||
'heartratewaveform', 'identityobservation', 'biometric', 'biometrics', 'face', 'faces', 'faceembedding',
|
||||
]);
|
||||
const SPACES_ENV_ALLOWLIST = Object.freeze([
|
||||
...DEFAULT_ENV_ALLOWLIST,
|
||||
// Operators may bind an MCP server to a credential file without putting a
|
||||
@@ -35,24 +49,26 @@ function normalizeField(value) {
|
||||
return String(value).replace(/[^a-z0-9]/gi, '').toLowerCase();
|
||||
}
|
||||
|
||||
function assertBoundedValue(value, depth = 0) {
|
||||
function assertBoundedValue(value, depth = 0, state = { nodes: 0 }) {
|
||||
state.nodes += 1;
|
||||
if (state.nodes > MAX_JSON_NODES) throw new Error('JSON structure exceeds node bound');
|
||||
if (depth > MAX_JSON_DEPTH) throw new Error('JSON nesting is too deep');
|
||||
if (typeof value === 'string') {
|
||||
if (Buffer.byteLength(value, 'utf8') > MAX_STRING_BYTES) throw new Error('string exceeds bound');
|
||||
return;
|
||||
}
|
||||
if (Array.isArray(value)) {
|
||||
if (value.length > 1000) throw new Error('array exceeds bound');
|
||||
for (const item of value) assertBoundedValue(item, depth + 1);
|
||||
if (value.length > MAX_ARRAY_ITEMS) throw new Error('array exceeds bound');
|
||||
for (const item of value) assertBoundedValue(item, depth + 1, state);
|
||||
return;
|
||||
}
|
||||
if (!value || typeof value !== 'object') return;
|
||||
const entries = Object.entries(value);
|
||||
if (entries.length > 128) throw new Error('object exceeds bound');
|
||||
if (entries.length > MAX_OBJECT_KEYS) throw new Error('object exceeds bound');
|
||||
for (const [key, item] of entries) {
|
||||
if (Buffer.byteLength(key, 'utf8') > MAX_STRING_BYTES) throw new Error('object key exceeds bound');
|
||||
if (FORBIDDEN_FIELDS.has(normalizeField(key))) throw new Error(`forbidden raw field: ${key}`);
|
||||
assertBoundedValue(item, depth + 1);
|
||||
assertBoundedValue(item, depth + 1, state);
|
||||
}
|
||||
}
|
||||
|
||||
@@ -61,7 +77,7 @@ function nonEmptyString(value) {
|
||||
}
|
||||
|
||||
/** Parse and independently enforce the metaharness semantic boundary. */
|
||||
export function parseSpacesOutput(stdout) {
|
||||
export function parseSpacesOutput(stdout, expectedKind = undefined) {
|
||||
if (Buffer.byteLength(String(stdout), 'utf8') > MAX_CLI_JSON_BYTES) {
|
||||
throw new Error('CLI response exceeds bound');
|
||||
}
|
||||
@@ -72,29 +88,76 @@ export function parseSpacesOutput(stdout) {
|
||||
throw new Error('CLI response is not JSON');
|
||||
}
|
||||
assertBoundedValue(response);
|
||||
if (!response || response.object !== 'list' || !Array.isArray(response.data) || response.data.length > MAX_SPACES) {
|
||||
if (!response || response.object !== 'list' || !Array.isArray(response.data) || response.data.length > MAX_RESOURCES) {
|
||||
throw new Error('invalid list envelope');
|
||||
}
|
||||
const versioned = response.schemaVersion !== undefined || response.kind !== undefined;
|
||||
if (versioned && (response.schemaVersion !== '1.0' || !SPATIAL_RESOURCE_KINDS.includes(response.kind)
|
||||
|| (expectedKind !== undefined && response.kind !== expectedKind))) {
|
||||
throw new Error('invalid spatial contract version or kind');
|
||||
}
|
||||
const boundary = response.boundary;
|
||||
if (!boundary || boundary.authoritativeState !== 'HomeCore Edge' || !Array.isArray(boundary.excluded)) {
|
||||
if (!boundary || boundary.authoritativeState !== 'HomeCore Edge' || !Array.isArray(boundary.excluded)
|
||||
|| !boundary.excluded.every((item) => typeof item === 'string')) {
|
||||
throw new Error('incomplete edge privacy boundary');
|
||||
}
|
||||
for (const required of REQUIRED_EXCLUSIONS) {
|
||||
if (!boundary.excluded.includes(required)) throw new Error('incomplete edge privacy boundary');
|
||||
}
|
||||
for (const space of response.data) {
|
||||
if (!space || !nonEmptyString(space.id) || !nonEmptyString(space.tenantId)
|
||||
|| !nonEmptyString(space.siteId) || !nonEmptyString(space.name)) {
|
||||
throw new Error('space identity is incomplete');
|
||||
for (const item of response.data) {
|
||||
if (!item || !ID_RE.test(String(item.id ?? '')) || !nonEmptyString(item.tenantId)) {
|
||||
throw new Error('spatial identity is incomplete');
|
||||
}
|
||||
if (!['P2', 'P3'].includes(space.privacy) || space.state?.classification !== 'P2') {
|
||||
if (!['P2', 'P3'].includes(item.privacy)) {
|
||||
throw new Error('non-semantic privacy class');
|
||||
}
|
||||
const confidence = space.state?.confidence;
|
||||
const confidence = versioned ? item.confidence : item.state?.confidence;
|
||||
if (confidence !== null && confidence !== undefined
|
||||
&& (typeof confidence !== 'number' || !Number.isFinite(confidence) || confidence < 0 || confidence > 1)) {
|
||||
throw new Error('invalid confidence');
|
||||
}
|
||||
if (!versioned) {
|
||||
if (!nonEmptyString(item.siteId) || !nonEmptyString(item.name) || item.state?.classification !== 'P2') {
|
||||
throw new Error('space identity is incomplete');
|
||||
}
|
||||
continue;
|
||||
}
|
||||
if (!UUID_RE.test(String(item.workspaceId ?? '')) || item.kind !== response.kind
|
||||
|| item.schemaVersion !== '1.0' || !nonEmptyString(item.messageId)
|
||||
|| !Number.isSafeInteger(item.eventSequence) || item.eventSequence < 0
|
||||
|| !Number.isSafeInteger(item.version) || item.version < 1
|
||||
|| !nonEmptyString(item.observedAt) || !Number.isFinite(Date.parse(item.observedAt))
|
||||
|| (item.expiresAt !== null && item.expiresAt !== undefined
|
||||
&& (!nonEmptyString(item.expiresAt) || !Number.isFinite(Date.parse(item.expiresAt))))
|
||||
|| !item.attributes || Array.isArray(item.attributes) || typeof item.attributes !== 'object'
|
||||
|| !item.provenance || Array.isArray(item.provenance) || typeof item.provenance !== 'object') {
|
||||
throw new Error('versioned spatial identity is incomplete');
|
||||
}
|
||||
if (['buildings', 'floors', 'spaces', 'zones', 'entities', 'events', 'alerts'].includes(response.kind)
|
||||
&& !nonEmptyString(item.siteId)) throw new Error('spatial parent is incomplete');
|
||||
if (response.kind === 'floors' && !nonEmptyString(item.buildingId)) throw new Error('spatial parent is incomplete');
|
||||
if (response.kind === 'spaces' && (!nonEmptyString(item.buildingId) || !nonEmptyString(item.floorId))) {
|
||||
throw new Error('spatial parent is incomplete');
|
||||
}
|
||||
if (['zones', 'entities', 'events', 'alerts'].includes(response.kind) && !nonEmptyString(item.spaceId)) {
|
||||
throw new Error('spatial parent is incomplete');
|
||||
}
|
||||
if (response.kind === 'entities'
|
||||
&& (!['sensor', 'person', 'object', 'track'].includes(item.entityType)
|
||||
|| (['person', 'track'].includes(item.entityType) && item.identityMode !== 'anonymous'))) {
|
||||
throw new Error('entity privacy contract is invalid');
|
||||
}
|
||||
if (response.kind === 'events' && !nonEmptyString(item.eventType)) throw new Error('event type is missing');
|
||||
if (response.kind === 'alerts'
|
||||
&& (!nonEmptyString(item.alertType) || !['info', 'warning', 'critical'].includes(item.severity)
|
||||
|| !['open', 'acknowledged', 'resolved'].includes(item.status))) {
|
||||
throw new Error('alert contract is invalid');
|
||||
}
|
||||
}
|
||||
if (versioned && response.nextCursor !== null && response.nextCursor !== undefined
|
||||
&& (!nonEmptyString(response.nextCursor) || response.nextCursor.length > 512
|
||||
|| /[\u0000-\u001f\u007f]/u.test(response.nextCursor))) {
|
||||
throw new Error('invalid next cursor');
|
||||
}
|
||||
return response;
|
||||
}
|
||||
@@ -125,7 +188,23 @@ export async function listCognitumSpaces(input = {}, options = {}) {
|
||||
};
|
||||
}
|
||||
|
||||
const spacesArgs = ['spaces', '--json', '--base-url', DEFAULT_BASE_URL];
|
||||
const resource = input.resource || 'spaces';
|
||||
if (!SPATIAL_RESOURCE_KINDS.includes(resource)) {
|
||||
return { ok: false, reason: 'invalid_resource' };
|
||||
}
|
||||
const limit = input.limit === undefined ? 50 : input.limit;
|
||||
if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100) {
|
||||
return { ok: false, reason: 'invalid_limit' };
|
||||
}
|
||||
if (input.cursor !== undefined
|
||||
&& (typeof input.cursor !== 'string' || input.cursor.length === 0 || input.cursor.length > 512 || /[\u0000-\u001f\u007f]/u.test(input.cursor))) {
|
||||
return { ok: false, reason: 'invalid_cursor' };
|
||||
}
|
||||
const spacesArgs = [
|
||||
'spaces', '--json', '--base-url', DEFAULT_BASE_URL,
|
||||
'--resource', resource, '--limit', String(limit),
|
||||
];
|
||||
if (input.cursor) spacesArgs.push('--cursor', input.cursor);
|
||||
if (input.credentials_path) spacesArgs.push('--credentials-path', input.credentials_path);
|
||||
|
||||
let command;
|
||||
@@ -158,7 +237,7 @@ export async function listCognitumSpaces(input = {}, options = {}) {
|
||||
|
||||
let response;
|
||||
try {
|
||||
response = parseSpacesOutput(result.stdout);
|
||||
response = parseSpacesOutput(result.stdout, resource);
|
||||
} catch (error) {
|
||||
return {
|
||||
ok: false,
|
||||
@@ -173,6 +252,9 @@ export async function listCognitumSpaces(input = {}, options = {}) {
|
||||
authentication: 'oauth',
|
||||
via,
|
||||
count: response.data.length,
|
||||
resource,
|
||||
schemaVersion: response.schemaVersion,
|
||||
nextCursor: response.nextCursor ?? null,
|
||||
data: response.data,
|
||||
boundary: response.boundary,
|
||||
authority: 'Read-only tenant/workspace projection; this result grants no action, write, pairing, or actuator authority.',
|
||||
|
||||
@@ -292,12 +292,15 @@ export const TOOLS = {
|
||||
},
|
||||
|
||||
ruview_spaces_list: {
|
||||
title: 'List Cognitum Spaces',
|
||||
description: 'List the authenticated tenant/workspace Cognitum Spaces projection through the hardened wifi-densepose OAuth client. Never accepts tokens or API keys. MCP use requires the credential-use grant; an expired OAuth session may rotate its stored refresh credential.',
|
||||
title: 'List Cognitum Spatial Resources',
|
||||
description: 'Page sites, buildings, floors, spaces, zones, anonymous entities, semantic events, or alerts in the authenticated tenant/workspace through the hardened wifi-densepose OAuth client. Never accepts tokens, API keys, writes, approvals, or action authority.',
|
||||
inputSchema: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
credentials_path: { type: 'string', minLength: 1, maxLength: 4096, description: 'CLI only: OAuth credential file. MCP operators must set RUVIEW_CREDENTIALS_PATH in the server environment.' },
|
||||
resource: { type: 'string', enum: ['sites', 'buildings', 'floors', 'spaces', 'zones', 'entities', 'events', 'alerts'], description: 'Versioned spatial collection. Default: spaces.' },
|
||||
limit: { type: 'number', minimum: 1, maximum: 100, description: 'Page size. Default: 50.' },
|
||||
cursor: { type: 'string', minLength: 1, maxLength: 512, description: 'Opaque cursor from the prior page.' },
|
||||
},
|
||||
},
|
||||
async handler(args = {}, context = {}) {
|
||||
|
||||
@@ -4,15 +4,18 @@ import assert from 'node:assert/strict';
|
||||
import { listCognitumSpaces, parseSpacesOutput } from '../src/spaces.js';
|
||||
import { runTool } from '../src/tools.js';
|
||||
|
||||
function validResponse() {
|
||||
function validResponse(kind = 'spaces') {
|
||||
return {
|
||||
object: 'list',
|
||||
kind,
|
||||
schemaVersion: '1.0',
|
||||
data: [{
|
||||
id: 'room-1', tenantId: 'tenant-1', workspaceId: 'workspace-1', siteId: 'site-1', name: 'Room',
|
||||
version: 1, privacy: 'P2', status: 'live', connection: 'connected',
|
||||
state: { occupancy: 1, confidence: 0.9, observedAt: null, freshnessMs: 5, classification: 'P2', uncertainty: null, evidence: [] },
|
||||
provenance: {}, hardware: {}, dataBoundary: {}, observedAt: null, expiresAt: null,
|
||||
id: 'room-1', tenantId: 'tenant-1', workspaceId: '11111111-1111-7111-8111-111111111111', siteId: 'site-1', name: 'Room',
|
||||
buildingId: 'building-1', floorId: 'floor-1', kind, schemaVersion: '1.0',
|
||||
messageId: 'message-1', eventSequence: 1, version: 1, privacy: 'P2',
|
||||
confidence: 0.9, provenance: {}, attributes: {}, observedAt: '2026-08-19T00:00:00Z', expiresAt: null,
|
||||
}],
|
||||
nextCursor: null,
|
||||
boundary: {
|
||||
authoritativeState: 'HomeCore Edge',
|
||||
cloudRole: 'tenant-scoped semantic synchronization',
|
||||
@@ -23,7 +26,7 @@ function validResponse() {
|
||||
|
||||
test('Spaces adapter invokes OAuth-only CLI args in a scrubbed environment', async () => {
|
||||
const credentialPath = 'C:/private/ruview-credentials.json';
|
||||
const secretApiKey = 'cog_DO_NOT_FORWARD';
|
||||
const secretApiKey = ['cog', 'DO', 'NOT', 'FORWARD'].join('_');
|
||||
let observed;
|
||||
const result = await listCognitumSpaces(
|
||||
{ credentials_path: credentialPath },
|
||||
@@ -43,7 +46,8 @@ test('Spaces adapter invokes OAuth-only CLI args in a scrubbed environment', asy
|
||||
assert.equal(result.count, 1);
|
||||
assert.equal(observed.command, 'wifi-densepose-test-double');
|
||||
assert.deepEqual(observed.args, [
|
||||
'spaces', '--json', '--base-url', 'https://api.cognitum.one', '--credentials-path', credentialPath,
|
||||
'spaces', '--json', '--base-url', 'https://api.cognitum.one', '--resource', 'spaces', '--limit', '50',
|
||||
'--credentials-path', credentialPath,
|
||||
]);
|
||||
assert.ok(observed.options.envAllowlist.includes('RUVIEW_CREDENTIALS_PATH'));
|
||||
assert.ok(!observed.options.envAllowlist.includes('COGNITUM_SPACES_API'));
|
||||
@@ -69,7 +73,7 @@ test('MCP denies a Spaces read before touching local credentials or the network'
|
||||
|
||||
test('metaharness rejects forbidden raw fields from a child process', () => {
|
||||
const response = validResponse();
|
||||
response.data[0].state.raw_csi = [1, 2, 3];
|
||||
response.data[0].attributes.raw_csi = [1, 2, 3];
|
||||
assert.throws(() => parseSpacesOutput(JSON.stringify(response)), /forbidden raw field/i);
|
||||
});
|
||||
|
||||
@@ -79,12 +83,60 @@ test('metaharness rejects incomplete privacy boundaries and invalid confidence',
|
||||
assert.throws(() => parseSpacesOutput(JSON.stringify(incomplete)), /incomplete edge privacy boundary/i);
|
||||
|
||||
const invalid = validResponse();
|
||||
invalid.data[0].state.confidence = 2;
|
||||
invalid.data[0].confidence = 2;
|
||||
assert.throws(() => parseSpacesOutput(JSON.stringify(invalid)), /invalid confidence/i);
|
||||
});
|
||||
|
||||
test('versioned hierarchy, events, alerts, and cursor args stay OAuth-only', async () => {
|
||||
let observed;
|
||||
const response = validResponse('events');
|
||||
response.data[0].spaceId = 'room-1';
|
||||
response.data[0].eventType = 'occupancy.changed';
|
||||
response.data[0].buildingId = null;
|
||||
response.data[0].floorId = null;
|
||||
const result = await listCognitumSpaces(
|
||||
{ resource: 'events', limit: 25, cursor: 'opaque-cursor' },
|
||||
{
|
||||
source: 'mcp',
|
||||
binary: 'wifi-densepose-test-double',
|
||||
env: { PATH: 'test-path', COGNITUM_SPACES_API: 'cog_never_forward' },
|
||||
execute: async (command, args, options) => {
|
||||
observed = { command, args, options };
|
||||
return { stdout: JSON.stringify(response), stderr: '', code: 0 };
|
||||
},
|
||||
},
|
||||
);
|
||||
assert.equal(result.ok, true);
|
||||
assert.equal(result.resource, 'events');
|
||||
assert.deepEqual(observed.args, [
|
||||
'spaces', '--json', '--base-url', 'https://api.cognitum.one', '--resource', 'events', '--limit', '25',
|
||||
'--cursor', 'opaque-cursor',
|
||||
]);
|
||||
assert.ok(!observed.options.envAllowlist.includes('COGNITUM_SPACES_API'));
|
||||
});
|
||||
|
||||
test('metaharness rejects raw aliases and malformed kind-specific records', () => {
|
||||
const raw = validResponse();
|
||||
raw.data[0].attributes.packet_capture = 'forbidden';
|
||||
assert.throws(() => parseSpacesOutput(JSON.stringify(raw), 'spaces'), /forbidden raw field/i);
|
||||
|
||||
const entity = validResponse('entities');
|
||||
entity.data[0].spaceId = 'room-1';
|
||||
entity.data[0].entityType = 'person';
|
||||
entity.data[0].identityMode = 'named';
|
||||
assert.throws(() => parseSpacesOutput(JSON.stringify(entity), 'entities'), /entity privacy contract/i);
|
||||
|
||||
const invalidWorkspace = validResponse();
|
||||
invalidWorkspace.data[0].workspaceId = 'workspace-1';
|
||||
assert.throws(() => parseSpacesOutput(JSON.stringify(invalidWorkspace), 'spaces'), /versioned spatial identity/i);
|
||||
|
||||
const invalidTimestamp = validResponse();
|
||||
invalidTimestamp.data[0].observedAt = 'not-a-timestamp';
|
||||
assert.throws(() => parseSpacesOutput(JSON.stringify(invalidTimestamp), 'spaces'), /versioned spatial identity/i);
|
||||
});
|
||||
|
||||
test('command failures redact API keys and JWT-shaped tokens', async () => {
|
||||
const secret = 'cog_SUPER_SECRET_VALUE';
|
||||
const secret = `cog_${'test-value-'.repeat(4)}`;
|
||||
const jwt = 'eyJhbGciOiJFUzI1NiJ9.eyJzdWIiOiJ1c2VyLTEifQ.signature-material';
|
||||
const result = await listCognitumSpaces({}, {
|
||||
source: 'cli',
|
||||
|
||||
Reference in New Issue
Block a user