@toa.io/extensions.exposition 1.0.0-alpha.287 → 1.0.0-alpha.289

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.feature

@@ -245,3 +245,62 @@ Feature: Octets directive family
 
       Trailing slash is redundant
       """
+
+  Scenario: What sending a file takes
+    A file is not a value, so no schema states what may be sent — `octets:put` does, and a
+    client reads it where it reads everything else about the method.
+
+    When the following request is received:
+      """
+      OPTIONS /media/jpeg-or-png/ HTTP/1.1
+      host: nex.toa.io
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      Allow: POST
+
+      POST:
+        octets:
+          accept: image/jpeg,image/png
+          limit: 64MiB
+      """
+
+  Scenario: A limit is what a refusal reports
+    What a larger body is refused by is said the way the refusal says it.
+
+    When the following request is received:
+      """
+      OPTIONS /limit-1kb/ HTTP/1.1
+      host: nex.toa.io
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+
+      POST:
+        octets:
+          limit: 1kb
+      """
+
+  Scenario: Reading a file takes nothing to say
+    Only sending one says anything a schema does not; `octets:get` and `octets:delete` are
+    the request they look like.
+
+    When the following request is received:
+      """
+      OPTIONS /media/images/whatever/ 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:
+      """
+      octets:
+      """

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/Components.ts

@@ -5,6 +5,8 @@ import tsflow from 'cucumber-tsflow'
 
 import * as boot from '@toa.io/boot'
 import { type Connector } from '@toa.io/core'
+import { environment } from '@toa.io/generic'
+
 import { load as parse } from 'js-yaml'
 import { Gateway } from './Gateway.js'
 import { Workspace } from './Workspace.js'
@@ -68,7 +70,7 @@ export class Components {
   /** What the deployment would tell the values service, as the scenario needs it. */
   @given('the configuration values are deployed:')
   public deployValues(yaml: string): void {
-    process.env.TOA_CONFIGURATION_VALUES = JSON.stringify(parse(yaml))
+    environment.set('TOA_CONFIGURATION_VALUES', JSON.stringify(parse(yaml)))
   }
 
   @given('the `{word}` is stopped')
@@ -87,7 +89,7 @@ export class Components {
 
     await Promise.all(promises)
 
-    delete process.env.TOA_CONFIGURATION_VALUES
+    environment.delete('TOA_CONFIGURATION_VALUES')
   }
 
   private async runComponent(name: string, manifest?: object): Promise<void> {

package/features/steps/Database.ts

@@ -45,6 +45,10 @@ export class Database {
       document.CREATED ??= Date.now()
       document.UPDATED ??= document.CREATED
 
+      // a table states a timestamp as the entity carries it; the storage holds it as a date
+      for (const name of TIMESTAMPS)
+        if (typeof document[name] === 'number') document[name] = new Date(document[name])
+
       documents.push(document)
     }
 
@@ -96,5 +100,7 @@ export class Database {
   }
 }
 
+const TIMESTAMPS = ['CREATED', 'UPDATED', 'DELETED']
+
 /** Every fixture table names an `_id`, which is what a row is replaced by. */
-type Document = Record<string, string | number | boolean | null> & { _id: string }
+type Document = Record<string, string | number | boolean | Date | null> & { _id: string }

package/features/steps/Gateway.ts

@@ -2,10 +2,12 @@ import tsflow from 'cucumber-tsflow'
 
 import * as boot from '@toa.io/boot'
 import { type Connector } from '@toa.io/core'
+import { environment } from '@toa.io/generic'
+
 import { load as parse } from 'js-yaml'
 import { Factory } from '../../source/index.js'
 import * as syntax from '../../source/RTD/syntax/index.js'
-import { shortcuts } from '../../source/Directive.js'
+import { shortcuts } from '../../source/shortcuts.js'
 import { manifests } from './map.js'
 import { PORT, PROBE } from './Parameters.js'
 import type * as http from '../../source/HTTP/index.js'
@@ -26,7 +28,7 @@ export class Gateway {
     if (annotation['/'] !== undefined) {
       const tree = syntax.parse(annotation['/'], shortcuts)
 
-      process.env.TOA_EXPOSITION = JSON.stringify(tree)
+      environment.set('TOA_EXPOSITION', JSON.stringify(tree))
     }
 
     const { debug, authorities, bouncer, ip, oauth, rpc, mcp } = annotation
@@ -46,7 +48,7 @@ export class Gateway {
 
     if (mcp !== undefined) properties.mcp = mcp
 
-    process.env.TOA_EXPOSITION_PROPERTIES = JSON.stringify(properties)
+    environment.set('TOA_EXPOSITION_PROPERTIES', JSON.stringify(properties))
   }
 
   /**
@@ -75,8 +77,8 @@ export class Gateway {
       tree.routes.push(...node.routes)
     }
 
-    process.env.TOA_EXPOSITION = JSON.stringify(tree)
-    process.env.TOA_EXPOSITION_PROPERTIES = JSON.stringify(DEFAULT_PROPERTIES)
+    environment.set('TOA_EXPOSITION', JSON.stringify(tree))
+    environment.set('TOA_EXPOSITION_PROPERTIES', JSON.stringify(DEFAULT_PROPERTIES))
   }
 
   @given('the `{word}` configuration:')
@@ -90,7 +92,7 @@ export class Gateway {
     // scenario-scoped, as the secrets it may refer to are: a configuration left behind
     // outlives the secrets it points at, and the next scenario cannot resolve them
     this.written.push(key)
-    process.env[key] = JSON.stringify(configuration)
+    environment.set(key, JSON.stringify(configuration))
   }
 
   /** The secrets a scenario's configuration refers to. */
@@ -100,7 +102,7 @@ export class Gateway {
 
     for (const [name, value] of Object.entries(secrets)) {
       this.written.push(SECRET + name)
-      process.env[SECRET + name] = value
+      environment.set(SECRET + name, value)
     }
   }
 
@@ -111,8 +113,11 @@ export class Gateway {
 
   @given('the Gateway is running')
   public async start(): Promise<void> {
-    process.env.TOA_EXPOSITION ??= DEFAULT_TREE
-    process.env.TOA_EXPOSITION_PROPERTIES ??= JSON.stringify(DEFAULT_PROPERTIES)
+    if (!environment.has('TOA_EXPOSITION'))
+      environment.set('TOA_EXPOSITION', DEFAULT_TREE)
+
+    if (!environment.has('TOA_EXPOSITION_PROPERTIES'))
+      environment.set('TOA_EXPOSITION_PROPERTIES', JSON.stringify(DEFAULT_PROPERTIES))
 
     this.writeConfiguration()
 
@@ -141,14 +146,11 @@ export class Gateway {
 
   /** What the running gateway was built from: a different value is a different deployment. */
   private static signature(): string {
-    const configuration = Object.keys(process.env)
-      .filter((key) => key.startsWith('TOA_CONFIGURATION_'))
-      .sort()
-      .map((key) => [key, process.env[key]])
+    const configuration = Object.entries(environment.entries('TOA_CONFIGURATION_')).sort()
 
     return JSON.stringify([
-      process.env.TOA_EXPOSITION,
-      process.env.TOA_EXPOSITION_PROPERTIES,
+      environment.get('TOA_EXPOSITION'),
+      environment.get('TOA_EXPOSITION_PROPERTIES'),
       process.env.__TESTING_EXPOSITION_BRANCH_TTL,
       configuration
     ])
@@ -158,12 +160,12 @@ export class Gateway {
   public async cleanup(): Promise<void> {
     delete process.env.__TESTING_EXPOSITION_BRANCH_TTL
 
-    for (const key of this.written) delete process.env[key]
+    for (const key of this.written) environment.delete(key)
 
     this.written = []
 
-    delete process.env.TOA_EXPOSITION
-    delete process.env.TOA_EXPOSITION_PROPERTIES
+    environment.delete('TOA_EXPOSITION')
+    environment.delete('TOA_EXPOSITION_PROPERTIES')
   }
 
   @afterAll()
@@ -178,11 +180,11 @@ export class Gateway {
       const [name, namespace = 'default'] = id.split('.').reverse()
       const key = `TOA_CONFIGURATION_${namespace.toUpperCase()}_${name.toUpperCase()}`
 
-      process.env[key] ??= JSON.stringify(configuration)
+      if (!environment.has(key)) environment.set(key, JSON.stringify(configuration))
     }
 
     for (const [name, value] of Object.entries(DEFAULT_SECRETS))
-      process.env[SECRET + name] ??= value
+      if (!environment.has(SECRET + name)) environment.set(SECRET + name, value)
   }
 }
 
@@ -208,7 +210,7 @@ const DEFAULT_PROPERTIES: Partial<http.Options> = {
   port: PORT,
   probe: PROBE,
   // `npm run features:h2c` runs the whole suite over cleartext HTTP/2
-  protocol: process.env.TOA_EXPOSITION_PROTOCOL === 'h2c' ? 'h2c' : 'h1'
+  protocol: environment.get('TOA_EXPOSITION_PROTOCOL') === 'h2c' ? 'h2c' : 'h1'
 }
 
 // the identity components boot inside the gateway, and without a variable each would wait

package/features/steps/Parameters.ts

@@ -1,6 +1,7 @@
 import { join } from 'node:path'
 import * as dotenv from 'dotenv'
 import { setDefaultTimeout } from '@cucumber/cucumber'
+import { environment as variables } from '@toa.io/generic'
 
 dotenv.config({ path: join(import.meta.dirname, '.env') })
 
@@ -21,24 +22,41 @@ export class Parameters {
 
 setDefaultTimeout(60 * 1000)
 
-process.env.TOA_DEV = '1'
+variables.set('TOA_DEV', '1')
 
 // a reply is checked against what the operation declares, so the suite runs Toa under the
 // contract it asks applications to keep
-process.env.TOA_ENV ??= 'local'
+if (!variables.has('TOA_ENV')) variables.set('TOA_ENV', 'local')
 
 // the gateway answers for itself, as it does in a deployment: telemetry's probe tracks the
 // nested composition, which connects before route discovery settles
-process.env.TOA_TELEMETRY_READY ??= JSON.stringify(false)
+if (!variables.has('TOA_TELEMETRY_READY'))
+  variables.set('TOA_TELEMETRY_READY', JSON.stringify(false))
 
 // export traces to the local Tempo (`docker compose up tempo grafana`),
 // unavailability of the endpoint is harmless
-process.env.TOA_TELEMETRY_TRACES ??= JSON.stringify({
-  exporters: {
-    console: null,
-    otlp: { endpoint: 'http://localhost:31061' }
-  }
-})
+if (!variables.has('TOA_TELEMETRY_TRACES'))
+  variables.set(
+    'TOA_TELEMETRY_TRACES',
+    JSON.stringify({
+      exporters: {
+        console: null,
+        otlp: { endpoint: 'http://localhost:31061' }
+      }
+    })
+  )
+
+/*
+ * 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
 
@@ -132,10 +150,13 @@ const CLOUDINARY = {
   }
 }
 
-process.env.TOA_STORAGES = JSON.stringify({
-  octets: {
-    provider: 'tmp',
-    directory: Math.random().toString(36).substring(2)
-  },
-  ...(environment === undefined ? {} : CLOUDINARY)
-})
+variables.set(
+  'TOA_STORAGES',
+  JSON.stringify({
+    octets: {
+      provider: 'tmp',
+      directory: Math.random().toString(36).substring(2)
+    },
+    ...(environment === undefined ? {} : CLOUDINARY)
+  })
+)