@toa.io/extensions.exposition 1.0.0-alpha.286 → 1.0.0-alpha.288

package/features/introspection.feature

@@ -62,7 +62,12 @@ Feature: Introspection
           required:
             - title
             - volume
-        output: {}
+        output:
+          type: object
+          properties:
+            title:
+              type: string
+              maxLength: 64
         errors:
           - NO_WAY
           - WONT_CREATE
@@ -79,7 +84,8 @@ Feature: Introspection
         /:
           io:output: true
           GET:
-            mcp:tool: Every pot there is, newest first.
+            help:method:
+              description: Every pot there is, newest first.
             endpoint: enumerate
           POST: create
       """
@@ -214,6 +220,85 @@ Feature: Introspection
       POST:
       """
 
+  Scenario: A credential does not hide what is anonymous
+    A credential refuses an `anonymous` route because it would make the reply uncacheable,
+    and a description is not that reply — it is what the resource is, and it varies by who
+    asked in any case. Without this an identity would be told less than someone presenting
+    nothing at all.
+
+    Given the `pots` is running with the following manifest:
+      """yaml
+      exposition:
+        /:
+          isolated: true
+          anonymous: true
+          io:output: [id]
+          GET: enumerate
+      """
+    When the following request is received:
+      """
+      OPTIONS /pots/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      Allow: GET
+      """
+
+  Scenario: A method that takes an identity is not described to nobody
+    Which identity it is about cannot be told from a description, which has no route
+    variable to read. That there must be one can, and a caller with none is refused
+    whatever the value would have been — so they are not shown it.
+
+    Given the `identity.basic` database contains:
+      # developer:secret
+      | _id                              | authority | username  | password                                                     |
+      | efe3a65ebbee47ed95a73edd911ea328 | nex       | developer | $2b$10$ZRSKkgZoGnrcTNA5w5eCcu3pxDzdTduhteVYXcp56AaNcilNkwJ.O |
+    And the `identity.bans` database is empty
+    And the `pots` is running with the following manifest:
+      """yaml
+      exposition:
+        /:id:
+          isolated: true
+          io:output: [id]
+          GET:
+            anonymous: true
+            endpoint: observe
+          PATCH:
+            auth:id: id
+            endpoint: assign
+      """
+    When the following request is received:
+      """
+      OPTIONS /pots/:id/ HTTP/1.1
+      host: nex.toa.io
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      Allow: GET
+      """
+    And the reply does not contain:
+      """
+      PATCH:
+      """
+    When the following request is received:
+      """
+      OPTIONS /pots/:id/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      Allow: GET, PATCH
+      """
+
   Scenario: A resource the caller cannot reach at all
     Given the `pots` is running with the following manifest:
       """yaml
@@ -274,8 +359,9 @@ Feature: Introspection
       """
 
   Scenario: A property a header carries
-    `map:headers` fills the property from the request, so it is not the body's to send —
-    and the caller is told where it does go.
+    `map:headers` fills the property from the request, so it is not the body's to send.
+    Which header it reads is not answered: what an application takes off a request is its
+    own, and a caller has nowhere to put one.
 
     Given the `echo` is running with the following manifest:
       """yaml
@@ -299,16 +385,16 @@ Feature: Introspection
       Allow: PATCH
 
       PATCH:
-        headers:
-          a:
-            type: string
-            header: x-first
         input:
           type: object
           properties:
             b:
               type: string
       """
+    And the reply does not contain:
+      """
+      x-first
+      """
 
   Scenario: A property a segment carries under another name
     `map:segments` names the property differently from the segment it reads, so the route

package/features/map.feature

@@ -78,6 +78,7 @@ Feature: HTTP context mapping
     When the following request is received:
       """
       OPTIONS / HTTP/1.1
+      access-control-request-method: GET
       host: nex.toa.io
       origin: https://example.com
       """

package/features/mcp.feature

@@ -1,11 +1,12 @@
 @security
 Feature: Model Context Protocol
 
-  A tool is a procedure a method is published as. A method says so with `mcp:tool`, whose
-  value is what the tool is, and a default denies: a tree holds everything an application
-  serves and most of it is machinery a model has no business reading. What a tool takes and
-  answers is what the method says of itself, and what a caller may do with it is what `auth`
-  says.
+  A tool is a procedure a method is published as. A method says so with `mcp:tool`, and a
+  default denies: a tree holds everything an application serves and most of it is machinery
+  a model has no business reading. What the tool is called and what it is for is
+  `help:method`, which is what describes the method everywhere else as well. What a tool
+  takes and answers is what the method says of itself, and what a caller may do with it is
+  what `auth` says.
 
   What a tool is, is stated on the route and nowhere else. The operation states what it is
   too, and that is not this: one operation mounted on two routes is two tools. A `title`
@@ -30,20 +31,27 @@ Feature: Model Context Protocol
         /:
           io:output: [id, title, volume]
           GET:
-            mcp:tool: All the pots, newest first.
+            mcp:tool: true
+            help:method:
+              description: All the pots, newest first.
             endpoint: enumerate
           POST:
-            mcp:tool: Start a new pot brewing.
+            mcp:tool: true
+            help:method:
+              description: Start a new pot brewing.
             endpoint: create
           /:id:
             GET:
-              mcp:tool: One pot, by its id.
+              mcp:tool: true
+              help:method:
+                description: One pot, by its id.
               endpoint: observe
           /large:
             GET:
               query:
                 criteria: volume>=100
-              mcp:tool:
+              mcp:tool: true
+              help:method:
                 title: Large pots
                 description: The pots that hold a hundred or more, newest first.
               endpoint: enumerate
@@ -53,7 +61,9 @@ Feature: Model Context Protocol
             isolated: true
             GET:
               auth:role: admin
-              mcp:tool: Every pot there is, for whoever may see them all.
+              mcp:tool: true
+              help:method:
+                description: Every pot there is, for whoever may see them all.
               endpoint: enumerate
       """
     And the `pots` database contains:
@@ -256,6 +266,54 @@ Feature: Model Context Protocol
         code: -32601
       """
 
+  Scenario: A tool that takes an identity is not listed to nobody
+    `tools/list` answers what this caller may reach, and it is the description that decides
+    — the same one `OPTIONS` answers. A model is not shown a tool it would be refused.
+
+    Given the annotation:
+      """yaml
+      mcp:
+        name: Pots
+        anonymous: true
+      /:
+        anonymous: true
+        /pots/:id:
+          isolated: true
+          GET:
+            anonymous: true
+            mcp:tool: true
+            help:method: One pot, by its id.
+            dev:stub: []
+          PATCH:
+            auth:id: id
+            mcp:tool: true
+            help:method: Change your own pot.
+            dev:stub: []
+      """
+    When the following request is received:
+      """
+      POST /.mcp HTTP/1.1
+      host: nex.toa.io
+      accept: application/yaml
+      content-type: application/json
+      mcp-protocol-version: 2026-07-28
+      mcp-method: tools/list
+
+      {"jsonrpc": "2.0", "id": 3, "method": "tools/list",
+       "params": {"_meta": {"io.modelcontextprotocol/protocolVersion": "2026-07-28",
+                            "io.modelcontextprotocol/clientCapabilities": {}}}}
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+
+      - name: pots._id.GET
+      """
+    And the reply does not contain:
+      """
+      pots._id.PATCH
+      """
+
   Scenario: A credential does not hide an anonymous tool
     A client here always presents one, and what refuses a credentialed request at an
     `anonymous` route is that the reply would not be cacheable — which a tool's is not.
@@ -563,7 +621,9 @@ Feature: Model Context Protocol
         /:
           io:output: true
           GET:
-            mcp:tool: Refuses, with what it was given.
+            mcp:tool: true
+            help:method:
+              description: Refuses, with what it was given.
             endpoint: error
       """
     When the following request is received:
@@ -605,7 +665,9 @@ Feature: Model Context Protocol
         /:
           io:output: true
           GET:
-            mcp:tool: Answers with what it was given.
+            mcp:tool: true
+            help:method:
+              description: Answers with what it was given.
             endpoint: echo
       """
     When the following request is received:

package/features/methods.feature

@@ -37,11 +37,12 @@ Feature: Supported methods
     When the following request is received:
       """
       OPTIONS / HTTP/1.1
+      access-control-request-method: GET
       host: nex.toa.io
       origin: https://hello.world
       """
     Then the following reply is sent:
       """
       204 No Content
-      access-control-allow-methods: GET, POST, PUT, PATCH, DELETE, LOCK, UNLOCK
+      access-control-allow-methods: GET, POST, PUT, PATCH, DELETE, LOCK, UNLOCK, OPTIONS
       """

package/features/oauth.grants.feature

@@ -26,7 +26,9 @@ Feature: Authorization code flow
         /pots:
           anyone: true
           GET:
-            mcp:tool: Every pot there is.
+            mcp:tool: true
+            help:method:
+              description: Every pot there is.
             dev:stub: Kettles and teapots.
       """
     When the following request is received:

package/features/octets.download.feature

@@ -183,6 +183,7 @@ Feature: Download external resources
     When the following request is received:
       """
       OPTIONS / HTTP/1.1
+      access-control-request-method: GET
       host: nex.toa.io
       origin: https://hello.world
       """

package/features/octets.meta.feature

@@ -105,6 +105,7 @@ Feature: Octets metadata
     When the following request is received:
       """
       OPTIONS / HTTP/1.1
+      access-control-request-method: GET
       host: nex.toa.io
       origin: https://example.com
       """

package/features/site/_app/immutable/asset.js

@@ -0,0 +1 @@
+export const hashed = true

package/features/site/index.html

@@ -0,0 +1,10 @@
+<!doctype html>
+<!-- stands in for what `ui` builds; the scenarios are about the server, not the page -->
+<html lang="en">
+  <head>
+    <title>fixture</title>
+  </head>
+  <body>
+    the page
+  </body>
+</html>

package/features/steps/Parameters.ts

@@ -40,6 +40,18 @@ process.env.TOA_TELEMETRY_TRACES ??= JSON.stringify({
   }
 })
 
+/*
+ * The page the gateway serves at `/.discovery/`, pointed at a fixture: the scenarios are
+ * about the server, not the page, and none of them should need a UI build. Set here rather
+ * than in a step because the gateway is not rebuilt between scenarios that share its
+ * signature, so one flipping this would silently read whatever the last one left.
+ */
+process.env.__TESTING_EXPOSITION_DISCOVERY_ROOT = join(
+  import.meta.dirname,
+  '..',
+  'site'
+)
+
 const environment = process.env.CLOUDINARY_ENVIRONMENT
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/extensions.exposition",
-  "version": "1.0.0-alpha.286",
+  "version": "1.0.0-alpha.288",
   "type": "module",
   "description": "Toa Exposition",
   "author": "temich <tema.gurtovoy@gmail.com>",
@@ -20,9 +20,9 @@
   "dependencies": {
     "@node-rs/bcrypt": "1.10.8",
     "@simplewebauthn/server": "14.0.0",
-    "@toa.io/core": "1.0.0-alpha.286",
+    "@toa.io/core": "1.0.0-alpha.288",
     "@toa.io/generic": "1.0.0-alpha.286",
-    "@toa.io/schemas": "1.0.0-alpha.286",
+    "@toa.io/schemas": "1.0.0-alpha.287",
     "content-type": "3.0.0",
     "jose": "6.2.10",
     "js-yaml": "5.4.1",
@@ -48,6 +48,8 @@
     "transpile:otp": "tsc -p ./components/identity.otp",
     "transpile:clients": "tsc -p ./components/identity.clients",
     "transpile:grants": "tsc -p ./components/identity.grants",
+    "build:ui": "npm --prefix ui ci && npm --prefix ui run build",
+    "prepack": "npm run build:ui",
     "features": "TSX_TSCONFIG_PATH=features/steps/tsconfig.json NODE_OPTIONS=--import=tsx cucumber-js",
     "features:h2c": "TOA_EXPOSITION_PROTOCOL=h2c TOA_AGENT_PROTOCOL=h2c TSX_TSCONFIG_PATH=features/steps/tsconfig.json NODE_OPTIONS=--import=tsx cucumber-js",
     "features:security": "TSX_TSCONFIG_PATH=features/steps/tsconfig.json NODE_OPTIONS=--import=tsx cucumber-js --tags @security",
@@ -58,5 +60,5 @@
     "@types/cors": "2.8.19",
     "@types/negotiator": "0.6.5"
   },
-  "gitHead": "81f3d0688f17668b902be336d1749cc715edcdb6"
+  "gitHead": "d3d696f0a4e287c3c297ac81028d600ad7574112"
 }

package/readme.md

@@ -211,6 +211,9 @@ See also [telemetry ready probe](../telemetry/readme.md#ready-probe) and
 - [Resource Tree Definition](documentation/tree.md)
 - [Identity authentication](documentation/identity.md)
 - [Access authorization](documentation/access.md)
+- [Resource introspection](documentation/introspection.md)
+- [Help](documentation/help.md)
+- [Resource discovery](documentation/discovery.md)
 - [OAuth authorization server](documentation/oauth.md)
 - [Consent](documentation/consent.md)
 - [BLOBs](documentation/octets.md)

package/source/Directive.ts

@@ -206,6 +206,10 @@ export class DirectivesFactory implements RTD.DirectiveFactory {
     return directives
   }
 
+  public inheritable(directive: RTD.syntax.Directive): boolean {
+    return this.families[directive.family]?.inherited !== false
+  }
+
   public dispose(): void {
     for (const directives of this.instances) directives.dispose()
   }

package/source/Discovery/Explorer.ts

@@ -0,0 +1,34 @@
+import * as http from '../HTTP/index.js'
+import { BRANCH_TTL } from '../const.js'
+import { describe } from './tree.js'
+import type { Tree } from '../RTD/index.js'
+
+/**
+ * What an application serves, for every route at once. Each entry is what `OPTIONS` on that
+ * path answers, so a key taken from here is a request that can be made.
+ */
+export class Explorer {
+  private readonly tree: Tree
+
+  public constructor(tree: Tree) {
+    this.tree = tree
+  }
+
+  public async process(context: http.Context): Promise<http.OutgoingMessage> {
+    if (context.request.method !== 'OPTIONS')
+      throw new http.MethodNotAllowed(new Headers({ allow: ALLOW }))
+
+    return {
+      body: await describe(this.tree, context),
+      headers: new Headers({
+        allow: ALLOW,
+        // it stands until a branch expires, and it is filtered by who asked
+        'cache-control': `private, max-age=${BRANCH_TTL / 1000}`,
+        vary: 'authorization'
+      })
+    }
+  }
+}
+
+/** The verbs of this path, which are not the verbs of the tree it answers with. */
+const ALLOW = 'GET, HEAD, OPTIONS'

package/source/Discovery/Site.test.ts

@@ -0,0 +1,147 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import { Readable } from 'node:stream'
+import * as path from 'node:path'
+import * as fs from 'node:fs'
+import * as os from 'node:os'
+
+import { Site } from './Site.js'
+import * as http from '../HTTP/index.js'
+import type { Input, Output } from '../io.js'
+
+const root = fs.mkdtempSync(path.join(os.tmpdir(), 'discovery-'))
+
+fs.mkdirSync(path.join(root, '_app', 'immutable'), { recursive: true })
+fs.writeFileSync(path.join(root, 'index.html'), 'the page\n')
+fs.writeFileSync(path.join(root, 'favicon.ico'), 'icon')
+fs.writeFileSync(path.join(root, '_app', 'immutable', 'asset.js'), 'export {}\n')
+
+const empty = fs.mkdtempSync(path.join(os.tmpdir(), 'discovery-empty-'))
+
+const site = new Site(root)
+
+const input = (url: string, method = 'GET'): Input =>
+  ({
+    request: { method, headers: {} },
+    url: new URL(url, 'http://nex.toa.io')
+  }) as unknown as Input
+
+const header = (output: Output, name: string): string | null =>
+  output?.headers?.get(name) ?? null
+
+describe('discovery site', () => {
+  it('should leave a path outside its prefix alone', () => {
+    assert.equal(site.intercept(input('/')), null)
+    assert.equal(site.intercept(input('/pots/')), null)
+  })
+
+  it('should not claim a path that merely starts like its own', () => {
+    assert.equal(site.intercept(input('/.discoveryable/')), null)
+  })
+
+  it('should send the bare path to the directory it is', () => {
+    const output = site.intercept(input('/.discovery'))
+
+    assert.equal(output?.status, 302)
+    assert.equal(header(output, 'location'), '/.discovery/')
+  })
+
+  it('should keep the query when it redirects', () => {
+    const output = site.intercept(input('/.discovery?at=/pots'))
+
+    assert.equal(header(output, 'location'), '/.discovery/?at=/pots')
+  })
+
+  it('should serve the page', () => {
+    const output = site.intercept(input('/.discovery/'))
+
+    assert.equal(output?.status, 200)
+    assert.equal(header(output, 'content-type'), 'text/html; charset=utf-8')
+    assert.equal(header(output, 'cache-control'), 'no-cache')
+  })
+
+  it('should always carry a content-type and a stream', () => {
+    // a stream without one is framed as `multipart/*`, and the page arrives as an envelope
+    for (const url of ['/.discovery/', '/.discovery/_app/immutable/asset.js']) {
+      const output = site.intercept(input(url))
+
+      assert.ok(output?.headers?.has('content-type'), url)
+      assert.ok(output?.body instanceof Readable, url)
+    }
+  })
+
+  it('should hold a hashed asset forever and an icon for a day', () => {
+    assert.equal(
+      header(site.intercept(input('/.discovery/_app/immutable/asset.js')), 'cache-control'),
+      'public, max-age=31536000, immutable'
+    )
+    assert.equal(
+      header(site.intercept(input('/.discovery/favicon.ico')), 'cache-control'),
+      'public, max-age=86400'
+    )
+  })
+
+  it('should fall back to the page for anything that could be a route', () => {
+    const output = site.intercept(input('/.discovery/pots/:id'))
+
+    assert.equal(header(output, 'content-type'), 'text/html; charset=utf-8')
+  })
+
+  it('should refuse an asset that is not there', () => {
+    // a missing asset is missing, however much a route can look like one
+    assert.throws(
+      () => site.intercept(input('/.discovery/_app/immutable/gone.js')),
+      http.NotFound
+    )
+  })
+
+  it('should refuse a path that climbs out of the root', () => {
+    /*
+     * An encoded separator is what reaches here: `..` and `%2e%2e` are dot segments and the
+     * URL parser has already collapsed them, but `%2f` keeps a segment whole through it and
+     * decodes to one afterwards.
+     */
+    for (const url of [
+      '/.discovery/%2f%2e%2e%2f%2e%2e%2fpackage.json',
+      '/.discovery/a%2f..%2f..%2fpackage.json',
+      '/.discovery/%2e%2e%2fpackage.json'
+    ])
+      assert.throws(() => site.intercept(input(url)), http.NotFound, url)
+  })
+
+  it('should never see a dot segment, which the URL parser collapses first', () => {
+    // `/.discovery/%2e%2e/x` is `/x`, which is not this prefix and not ours to answer
+    assert.equal(site.intercept(input('/.discovery/%2e%2e/%2e%2e/package.json')), null)
+    assert.equal(site.intercept(input('/.discovery/../../package.json')), null)
+  })
+
+  it('should report the length a GET would have returned, and open no stream', () => {
+    const output = site.intercept(input('/.discovery/', 'HEAD'))
+
+    assert.equal(output?.status, 200)
+    assert.equal(header(output, 'content-length'), '9')
+    assert.equal(output?.body, undefined)
+  })
+
+  it('should leave OPTIONS on the prefix to the tree', () => {
+    // it needs the identity, which is resolved after this stage
+    assert.equal(site.intercept(input('/.discovery', 'OPTIONS')), null)
+    assert.equal(site.intercept(input('/.discovery/', 'OPTIONS')), null)
+  })
+
+  it('should refuse every other method', () => {
+    assert.throws(() => site.intercept(input('/.discovery/', 'POST')), http.MethodNotAllowed)
+    assert.throws(
+      () => site.intercept(input('/.discovery/favicon.ico', 'OPTIONS')),
+      http.MethodNotAllowed
+    )
+  })
+
+  it('should say so where the page is not built', () => {
+    const output = new Site(empty).intercept(input('/.discovery/'))
+
+    assert.equal(output?.status, 503)
+    assert.equal(header(output, 'content-type'), 'text/plain; charset=utf-8')
+    assert.ok(output?.body instanceof Readable)
+  })
+})