SECTION-SOURCE-HOSTED-AUTHORIZATION-REVIEW-SPEC.md
file-level
1
files
1
commits
0
hotspots
0
🧊 dead
0
💥 blast risk
| 1 | # SectionSource Hosted Authorization Review Spec |
| 2 | |
| 3 | ## Simple Summary |
| 4 | |
| 5 | Phase 1H reviews the hosted authorization boundary for a future body-free hosted |
| 6 | `SectionSource v0` tool. |
| 7 | |
| 8 | This phase does not implement hosted MCP, Hub routes, search, persistence, Scooling runtime |
| 9 | behavior, section bodies, snippets, summaries, PageIndex, OCR, LLM calls, or provider |
| 10 | routing. |
| 11 | |
| 12 | ## Technical Summary |
| 13 | |
| 14 | Hosted SectionSource can expose private note-derived structure outside the local vault |
| 15 | process. Before that happens, the hosted boundary must be specified and tested separately |
| 16 | from the self-hosted MCP implementation. |
| 17 | |
| 18 | This review accepts only the authorization and lifecycle requirements for a future hosted |
| 19 | tool. The future hosted implementation must mirror hosted `get_note_outline`, |
| 20 | `get_document_tree`, and `get_metadata_facets`: |
| 21 | |
| 22 | - allow only roles explicitly approved by the hosted MCP ACL |
| 23 | - use the active hosted vault id |
| 24 | - use the effective canister user id |
| 25 | - send the same canister auth headers as adjacent hosted note-read tools |
| 26 | - normalize and reject unsafe paths before upstream fetch |
| 27 | - read one note from the canister |
| 28 | - derive body-free `SectionSource v0` metadata |
| 29 | - return hosted MCP JSON errors without body text, snippets, full frontmatter, absolute |
| 30 | paths, or raw upstream payloads |
| 31 | |
| 32 | ## Review Decision |
| 33 | |
| 34 | Phase 1H accepts the hosted authorization review only. |
| 35 | |
| 36 | It does not approve: |
| 37 | |
| 38 | - registering hosted `get_section_source` |
| 39 | - adding `get_section_source` to hosted role ACLs |
| 40 | - adding Hub REST, OpenAPI, Hub UI, or canister routes |
| 41 | - adding search, vectors, indexes, persistence, sidecars, or memory events |
| 42 | - adding Scooling runtime consumption |
| 43 | - returning note body text |
| 44 | - returning section body text |
| 45 | - returning snippets |
| 46 | - returning exact line ranges, byte offsets, or section body lengths |
| 47 | - adding summaries, OCR, PageIndex, LLM calls, or external provider routing |
| 48 | |
| 49 | ## Future Hosted Tool Shape |
| 50 | |
| 51 | A later hosted implementation may propose: |
| 52 | |
| 53 | ```text |
| 54 | get_section_source |
| 55 | ``` |
| 56 | |
| 57 | The future tool must accept exactly one field: |
| 58 | |
| 59 | ```json |
| 60 | { |
| 61 | "path": "inbox/example.md" |
| 62 | } |
| 63 | ``` |
| 64 | |
| 65 | Field rules: |
| 66 | |
| 67 | - `path` is required. |
| 68 | - `path` must be a string. |
| 69 | - `path` must be vault-relative. |
| 70 | - `path` must not be absolute. |
| 71 | - `path` must not escape the active vault. |
| 72 | - No batch paths are accepted. |
| 73 | - No body, snippet, search, filter, ranking, provider, classroom, or Scooling options are |
| 74 | accepted. |
| 75 | |
| 76 | ## Hosted Authorization Requirements |
| 77 | |
| 78 | The future hosted tool must preserve these requirements: |
| 79 | |
| 80 | - The caller must have an authenticated hosted MCP session. |
| 81 | - The caller's role must pass `mcp-tool-acl.mjs` for the tool name. |
| 82 | - The tool must use `ctx.vaultId` as the active vault boundary. |
| 83 | - The tool must use `ctx.canisterUserId` as the effective canister user boundary. |
| 84 | - The upstream note read must include the same hosted canister headers as `get_note`, |
| 85 | `get_document_tree`, and `get_metadata_facets`. |
| 86 | - The requested path must be normalized and rejected before upstream fetch if it is empty, |
| 87 | absolute, Windows-absolute, or traversal-like. |
| 88 | - Missing and unauthorized notes must not reveal more than adjacent hosted read tools. |
| 89 | - The returned `path` must be the normalized vault-relative request path, not an upstream |
| 90 | absolute path or raw canister path. |
| 91 | |
| 92 | ## Accepted Future Output |
| 93 | |
| 94 | The future hosted tool may return only the existing body-free `SectionSource v0` shape: |
| 95 | |
| 96 | ```json |
| 97 | { |
| 98 | "schema": "knowtation.section_source/v0", |
| 99 | "path": "inbox/example.md", |
| 100 | "title": "Example", |
| 101 | "sections": [ |
| 102 | { |
| 103 | "section_id": "inbox-example-md:h1-example-0001", |
| 104 | "heading_id": "h1-example-0001", |
| 105 | "level": 1, |
| 106 | "heading_path": ["Example"], |
| 107 | "heading_text": "Example", |
| 108 | "child_section_ids": [], |
| 109 | "body_available": true, |
| 110 | "body_returned": false, |
| 111 | "snippet_returned": false |
| 112 | } |
| 113 | ], |
| 114 | "truncated": false |
| 115 | } |
| 116 | ``` |
| 117 | |
| 118 | ## Explicitly Excluded Output |
| 119 | |
| 120 | The future hosted tool must not output: |
| 121 | |
| 122 | - note body text |
| 123 | - section body text |
| 124 | - snippets |
| 125 | - source excerpts |
| 126 | - full frontmatter |
| 127 | - absolute filesystem paths |
| 128 | - exact line ranges |
| 129 | - byte offsets |
| 130 | - section body lengths |
| 131 | - summaries |
| 132 | - vector scores |
| 133 | - provider payloads |
| 134 | - MCP resource URIs |
| 135 | - search results |
| 136 | - persistence ids |
| 137 | - Scooling adapter state |
| 138 | - raw upstream canister payloads |
| 139 | |
| 140 | ## Logging And Error Boundary |
| 141 | |
| 142 | The future hosted implementation must not log or return note body text, section body text, |
| 143 | snippets, full frontmatter, raw upstream payloads, gateway secrets, bearer tokens, or |
| 144 | provider payloads. |
| 145 | |
| 146 | Errors may report only bounded operational context: |
| 147 | |
| 148 | - invalid path |
| 149 | - missing note |
| 150 | - upstream status class |
| 151 | - generic authorization failure |
| 152 | - generic runtime failure |
| 153 | |
| 154 | Errors must not include note content, section content, raw frontmatter, absolute paths, auth |
| 155 | headers, request tokens, canister secrets, or provider payloads. |
| 156 | |
| 157 | ## Deletion, Export, And Staleness |
| 158 | |
| 159 | The reviewed hosted shape is on-demand and non-persistent. |
| 160 | |
| 161 | Until a separate persistence spec is accepted: |
| 162 | |
| 163 | - no hosted section sidecar is created |
| 164 | - no hosted section index is created |
| 165 | - no vector record is created |
| 166 | - no memory event is created |
| 167 | - no summary record is created |
| 168 | - export behavior remains unchanged |
| 169 | - deleting or editing a note leaves no SectionSource-derived hosted artifact to clean up |
| 170 | |
| 171 | ## Prompt-Injection Handling |
| 172 | |
| 173 | Hosted heading text and heading paths are private, untrusted source material. |
| 174 | |
| 175 | The future hosted tool must not treat headings or section text as instructions. Prompt-like |
| 176 | headings that ask the model to reveal secrets, bypass review, call providers, or disable |
| 177 | guardrails must remain inert text in the body-free response. |
| 178 | |
| 179 | ## Scooling Boundary |
| 180 | |
| 181 | This review does not approve Scooling runtime consumption. |
| 182 | |
| 183 | Future Scooling work must remain behind a Scooling-owned adapter and must not bypass |
| 184 | Knowtation hosted authorization, parse Markdown as the canonical section parser, persist |
| 185 | SectionSource as truth, expose private learner sections outside authorized contexts, or |
| 186 | treat section text as model instructions. |
| 187 | |
| 188 | ## Seven-Tier Test Requirements |
| 189 | |
| 190 | ### Unit |
| 191 | |
| 192 | - The hosted review spec documents role, vault, canister-user, path, logging, error, and |
| 193 | output boundaries. |
| 194 | - The future output allowlist matches body-free `SectionSource v0`. |
| 195 | - `body_returned` and `snippet_returned` remain false. |
| 196 | |
| 197 | ### Integration |
| 198 | |
| 199 | - Existing hosted `get_note_outline`, `get_document_tree`, and `get_metadata_facets` |
| 200 | patterns remain the only approved hosted comparison points. |
| 201 | - `get_section_source` remains absent from hosted ACLs in this review phase. |
| 202 | - Hosted runtime files contain no SectionSource builder or local note-read call. |
| 203 | |
| 204 | ### End To End |
| 205 | |
| 206 | - A hosted MCP client cannot list `get_section_source` in this review phase. |
| 207 | - A hosted MCP client cannot call `get_section_source` in this review phase. |
| 208 | - No hosted MCP flow returns section body text or snippets. |
| 209 | |
| 210 | ### Stress |
| 211 | |
| 212 | - Review checks stay bounded to hosted gateway files and SectionSource contract documents. |
| 213 | - No test scans a real vault. |
| 214 | - No test calls external providers. |
| 215 | |
| 216 | ### Data Integrity |
| 217 | |
| 218 | - This review writes no notes, sidecars, indexes, vectors, memory, summaries, or canister |
| 219 | state. |
| 220 | - No cached hosted section record is created. |
| 221 | - Export, delete, and edit behavior remain unchanged. |
| 222 | |
| 223 | ### Performance |
| 224 | |
| 225 | - The future hosted tool must read one note only. |
| 226 | - The future hosted tool must not scan the whole vault. |
| 227 | - The future hosted tool must not call external providers. |
| 228 | |
| 229 | ### Security |
| 230 | |
| 231 | - Hosted runtime exposure remains blocked in this phase. |
| 232 | - No note body text appears in hosted SectionSource output. |
| 233 | - No section body text appears in hosted SectionSource output. |
| 234 | - No snippets appear in hosted SectionSource output. |
| 235 | - No full frontmatter appears in hosted SectionSource output. |
| 236 | - No absolute filesystem paths appear in hosted SectionSource output. |
| 237 | - No MCP resource URI appears for hosted SectionSource content. |
| 238 | - Hosted, Scooling, classroom, search, persistence, and provider exposure remain blocked. |
| 239 | |
| 240 | ## Stop Conditions |
| 241 | |
| 242 | Stop and re-plan if hosted work requires: |
| 243 | |
| 244 | - returning note body text |
| 245 | - returning section body text |
| 246 | - returning snippets |
| 247 | - returning exact line ranges |
| 248 | - returning byte offsets |
| 249 | - returning section body lengths |
| 250 | - adding summaries |
| 251 | - adding search, vectors, indexes, persistence, sidecars, or memory events |
| 252 | - adding Hub REST, OpenAPI, Hub UI, canister routes, or Scooling runtime code |
| 253 | - sending note-derived content to LLMs, OCR, PageIndex, or external providers |
| 254 | - weakening active vault or effective canister-user boundaries |
| 255 | - weakening hosted role checks |
| 256 | - logging note content, auth headers, gateway secrets, bearer tokens, or provider payloads |
| 257 | |
| 258 | ## Acceptance Criteria |
| 259 | |
| 260 | Phase 1H is accepted when: |
| 261 | |
| 262 | - The hosted authorization boundary is documented before hosted runtime exposure. |
| 263 | - The future tool shape is limited to one vault-relative note path. |
| 264 | - The future output is limited to body-free `SectionSource v0` metadata. |
| 265 | - The review preserves active vault, effective canister-user, and role ACL boundaries. |
| 266 | - The review blocks hosted runtime registration in this phase. |
| 267 | - Tests prove hosted `get_section_source` remains absent from hosted MCP and ACL files. |
| 268 | - Tests prove hosted, Hub, search, persistence, Scooling, body, snippet, provider, OCR, |
| 269 | PageIndex, and LLM behavior remain blocked. |
| 270 | |
| 271 | ## Recommendation |
| 272 | |
| 273 | The Scooling adapter planning boundary is accepted separately in |
| 274 | `docs/SECTION-SOURCE-SCOOLING-ADAPTER-PLANNING-SPEC.md`. |
| 275 | |
| 276 | The Scooling adapter slice is complete in the Scooling repository at commit `ea5421e` |
| 277 | (`Add Scooling SectionSource transport boundary`). |
| 278 | |
| 279 | Proceed to a hosted implementation spec only if hosted SectionSource is required. |