@toa.io/extensions.exposition 1.0.0-alpha.271 → 1.0.0-alpha.273

package/components/identity.tokens/source/authenticate.ts

@@ -1,4 +1,3 @@
-import { Err } from 'error-value'
 import type { Maybe, Operation } from '@toa.io/types'
 import type { AuthenticateInput, AuthenticateOutput, Context } from './lib'
 
@@ -43,5 +42,10 @@ export class Computation implements Operation {
   }
 }
 
-const ERR_AUTHORITY = new Err('AUTHORITY_MISMATCH')
-const ERR_TOKEN_REVOKED = new Err('TOKEN_REVOKED')
+const ERR_AUTHORITY = new (class AuthorityMismatchError extends Error {
+  public readonly code = 'AUTHORITY_MISMATCH'
+})()
+
+const ERR_TOKEN_REVOKED = new (class TokenRevokedError extends Error {
+  public readonly code = 'TOKEN_REVOKED'
+})()

package/components/identity.tokens/source/decrypt.ts

@@ -1,5 +1,4 @@
 import { V3 } from 'paseto'
-import { Err } from 'error-value'
 import { LRUCache } from 'lru-cache'
 import { jweKey } from './lib'
 import { load } from './lib/jose'
@@ -161,6 +160,14 @@ interface KeyEntry {
   value: Key | null
 }
 
-const ERR_INVALID_TOKEN = new Err('INVALID_TOKEN')
-const ERR_INVALID_KEY = new Err('INVALID_KEY')
-const ERR_FORGED_KEY = new Err('FORGED_KEY')
+const ERR_INVALID_TOKEN = new (class InvalidTokenError extends Error {
+  public readonly code = 'INVALID_TOKEN'
+})()
+
+const ERR_INVALID_KEY = new (class InvalidKeyError extends Error {
+  public readonly code = 'INVALID_KEY'
+})()
+
+const ERR_FORGED_KEY = new (class ForgedKeyError extends Error {
+  public readonly code = 'FORGED_KEY'
+})()

package/components/identity.tokens/source/encrypt.ts

@@ -1,4 +1,3 @@
-import { Err } from 'error-value'
 import { jweKey } from './lib'
 import { load } from './lib/jose'
 import type { Operation, Maybe } from '@toa.io/types'
@@ -52,4 +51,6 @@ function within (scope: string, roles: string[]): boolean {
   return roles.some((role) => role === scope || scope.startsWith(role + ':'))
 }
 
-const ERR_INACCESSIBLE_SCOPE = new Err('INACCESSIBLE_SCOPE')
+const ERR_INACCESSIBLE_SCOPE = new (class InaccessibleScopeError extends Error {
+  public readonly code = 'INACCESSIBLE_SCOPE'
+})()

package/documentation/identity.md

@@ -181,7 +181,10 @@ name: users
 
 entity:
   schema:
-    name: string
+    type: object
+    properties:
+      name:
+        type: string
 
 exposition:
   /:

package/documentation/notes/throttling.md

@@ -2,7 +2,7 @@
 
 > **Superseded.** The design below was never implemented. `io:throttle` is now a
 > [GCRA](https://en.wikipedia.org/wiki/Generic_cell_rate_algorithm) deciding in each process, with
-> its state periodically reconciled through Redis by way of the `stash` extension's `meter`. It
+> its state periodically reconciled through Redis by way of the `atom` aspect's `meter`. It
 > answers the same forces the same way — decide locally, reconcile in the background, never fail the
 > request path — and the section below records what it does instead. The problem statement and the
 > forces have not changed.

package/features/cors.feature

@@ -20,7 +20,7 @@ Feature: CORS Support
       """
       204 No Content
       access-control-allow-credentials: true
-      access-control-allow-headers: accept, authorization, content-type, if-match, if-none-match, origin
+      access-control-allow-headers: accept, authorization, content-type, if-match, if-none-match
       access-control-allow-methods: GET, POST, PUT, PATCH, DELETE, LOCK, UNLOCK
       access-control-allow-origin: https://hello.world
       access-control-max-age: 3600

package/features/dev.feature

@@ -74,7 +74,7 @@ Feature: Dev
     Then the following reply is sent:
       """
       204 No Content
-      access-control-allow-headers: accept, authorization, content-type, if-match, if-none-match, faulty
+      access-control-allow-headers: accept, authorization, content-type, faulty, if-match, if-none-match
       """
     When the following request is received:
       """

package/features/identity.federation.feature

@@ -195,13 +195,14 @@ Feature: Identity Federation
 
     Then after 0.2 seconds
 
-    # check the role
+    # the role is checked over the id token: a Token carries the roles held when it
+    # was issued, and this one was issued before the grant
     When the following request is received:
       """
       GET /identity/ HTTP/1.1
       host: nex.toa.io
       accept: application/yaml
-      authorization: Token ${{ root.token }}
+      authorization: Bearer ${{ root.id_token }}
       """
     Then the following reply is sent:
       """

package/features/{identtiy.tokens.custom.feature → identity.tokens.custom.feature}

@@ -76,6 +76,45 @@ Feature: Custom tokens
       200 OK
       """
 
+  Scenario: Issuing a token for another identity
+    Given the `identity.basic` database contains:
+      | _id                              | authority | username  | password                                                     |
+      | efe3a65ebbee47ed95a73edd911ea328 | nex       | developer | $2b$10$ZRSKkgZoGnrcTNA5w5eCcu3pxDzdTduhteVYXcp56AaNcilNkwJ.O |
+      | e8e4f9c2a68d419b861403d71fabc915 | nex       | user      | $2b$10$Frszmrmsz9iwSXzBbRRMKeDVKsNxozkrLNSsN.SnVC.KPxLtQr/bK |
+    And the `identity.roles` database contains:
+      | _id                              | identity                         | role                      |
+      | 9c4702490ff84f2a9e1b1da2ab64bdd4 | efe3a65ebbee47ed95a73edd911ea328 | system:identity:tokens    |
+    When the following request is received:
+      """
+      POST /identity/tokens/e8e4f9c2a68d419b861403d71fabc915/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
+      content-type: application/yaml
+      accept: application/yaml
+
+      label: On behalf
+      lifetime: 600
+      """
+    Then the following reply is sent:
+      """
+      201 Created
+
+      token: ${{ token }}
+      """
+    When the following request is received:
+      """
+      GET /identity/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Token ${{ token }}
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+
+      id: e8e4f9c2a68d419b861403d71fabc915
+      """
+
   Scenario: Token with restricted scopes
     When the following request is received:
       """

package/features/introspection.feature

@@ -21,55 +21,48 @@ Feature: Introspection
       Allow: GET, POST
 
       GET:
-        type: array
-        items:
-          type: object
+        output:
+          type: array
+          items:
+            properties:
+              id:
+                type: string
+                pattern: ^[a-fA-F0-9]{32}$
+              title:
+                type: string
+                maxLength: 64
+              volume:
+                type: number
+                exclusiveMinimum: 0
+                maximum: 1000
+              temperature:
+                type: number
+                exclusiveMinimum: 0
+                maximum: 300
+            type: object
+            required:
+              - id
+              - title
+              - volume
+      POST:
+        input:
           properties:
-            id:
-              type: string
-              pattern: ^[a-fA-F0-9]{32}$
-            title:
-              type: string
-              maxLength: 64
-            volume:
-              type: number
-              exclusiveMinimum: 0
-              maximum: 1000
             temperature:
               type: number
               exclusiveMinimum: 0
               maximum: 300
-          additionalProperties: false
-          required:
-            - id
-            - title
-            - volume
-      POST:
-        input:
-          type: object
-          properties:
             title:
               type: string
               maxLength: 64
-            temperature:
-              type: number
-              exclusiveMinimum: 0
-              maximum: 300
             volume:
               type: number
               exclusiveMinimum: 0
               maximum: 1000
-          additionalProperties: false
+          type: object
           required:
             - title
             - volume
-        output:
-          type: object
-          properties:
-            id:
-              type: string
-              pattern: ^[a-fA-F0-9]{32}$
-          additionalProperties: false
+        output: {}
         errors:
           - NO_WAY
           - WONT_CREATE

package/features/map.feature

@@ -84,7 +84,7 @@ Feature: HTTP context mapping
     Then the following reply is sent:
       """
       204 No Content
-      access-control-allow-headers: accept, accept-language, authorization, content-type, foo, if-match, if-none-match, origin
+      access-control-allow-headers: accept, accept-language, authorization, content-type, foo, if-match, if-none-match
       """
 
   Scenario: Mapping the value of an arbitrary header

package/features/octets.download.feature

@@ -186,5 +186,5 @@ Feature: Download external resources
     Then the following reply is sent:
       """
       204 No Content
-      access-control-allow-headers: accept, authorization, content-attributes, content-location, content-type, if-match, if-none-match, origin
+      access-control-allow-headers: accept, authorization, content-attributes, content-location, content-type, if-match, if-none-match
       """

package/features/octets.meta.feature

@@ -111,6 +111,6 @@ Feature: Octets metadata
     Then the following reply is sent:
       """
       204 No Content
-      access-control-allow-headers: accept, authorization, content-attributes, content-location, content-type, if-match, if-none-match, origin
+      access-control-allow-headers: accept, authorization, content-attributes, content-location, content-type, if-match, if-none-match
       access-control-allow-origin: https://example.com
       """

package/features/passkeys.feature

@@ -20,16 +20,16 @@ Feature: Web Authentication
       201 Created
 
       challenge: ${{ challenge }}
-      identity: ${{ identity.id }}
       timeout: 60000
-      authenticatorSelection:
-        requireResidentKey: true
-        residentKey: required
+      identity: ${{ identity.id }}
       pubKeyCredParams:
         - type: public-key
           alg: -7
         - type: public-key
           alg: -257
+      authenticatorSelection:
+        residentKey: required
+        requireResidentKey: true
       """
 
   Scenario: Create a challenge to create a passkey to new identity
@@ -53,14 +53,14 @@ Feature: Web Authentication
       authorization: Token ${{ token }}
 
       challenge: ${{ challenge }}
-      identity: ${{ identity }}
       timeout: 60000
-      authenticatorSelection:
-        requireResidentKey: true
-        residentKey: required
+      identity: ${{ identity }}
       pubKeyCredParams:
         - type: public-key
           alg: -7
         - type: public-key
           alg: -257
+      authenticatorSelection:
+        residentKey: required
+        requireResidentKey: true
       """

package/features/query.feature

@@ -283,6 +283,33 @@ Feature: Queries
 
       Hello John
       """
+
+  # a declared parameter is taken out of the query string before what is left of it is
+  # answered for. A route that declares nothing but parameters is not queryable, so what
+  # is left has to be nothing at all
+  Scenario: Query parameters beside an undeclared one
+    Given the `echo` is running with the following manifest:
+      """yaml
+      exposition:
+        /:
+          GET:
+            io:output: true
+            query:
+              parameters: [name]
+            endpoint: compute
+      """
+    When the following request is received:
+      """
+      GET /echo/?name=John&foo=bar HTTP/1.1
+      host: nex.toa.io
+      accept: text/plain
+      """
+    Then the following reply is sent:
+      """
+      400 Bad Request
+
+      Query parameter 'foo' is not allowed
+      """
     When the following request is received:
       """
       GET /echo/?foo=bar HTTP/1.1

package/features/require.feature

@@ -27,7 +27,7 @@ Feature: Request requirements
     Then the following reply is sent:
       """
       201 Created
-      etag: ${{ etag }}
+      etag: "${{ etag }}"
 
       id: ${{ id }}
       """
@@ -53,7 +53,7 @@ Feature: Request requirements
       host: nex.toa.io
       content-type: application/yaml
       accept: text/plain
-      if-match: ${{ etag }}
+      if-match: "${{ etag }}"
 
       title: Bye
       """

package/features/response.feature

@@ -19,8 +19,8 @@ Feature: Response
     Then the following reply is sent:
       """
       200 OK
+      vary: origin, accept
       content-type: application/json
-      vary: accept
 
       {"hello":"world"}
       """
@@ -33,8 +33,8 @@ Feature: Response
     Then the following reply is sent:
       """
       200 OK
+      vary: origin, accept
       content-type: application/yaml
-      vary: accept
 
       hello: world
       """
@@ -48,8 +48,8 @@ Feature: Response
     Then the following reply is sent:
       """
       200 OK
+      vary: origin, accept
       content-type: application/json
-      vary: accept
 
       {"hello":"world"}
       """

package/features/steps/Components.ts

@@ -3,19 +3,22 @@ import { after, binding, given } from 'cucumber-tsflow'
 import * as boot from '@toa.io/boot'
 import { timeout } from '@toa.io/generic'
 import { type Connector } from '@toa.io/core'
-import { parse } from '@toa.io/yaml'
+import { load as parse } from 'js-yaml'
+import { Gateway } from './Gateway'
 import { Workspace } from './Workspace'
 import { components as map } from './map'
 
 const MAP = 'introspection'
 
-@binding([Workspace])
+@binding([Workspace, Gateway])
 export class Components {
   private readonly workspace: Workspace
+  private readonly gateway: Gateway
   private compositions: Record<string, Connector> = {}
 
-  public constructor (workspace: Workspace) {
+  public constructor (workspace: Workspace, gateway: Gateway) {
     this.workspace = workspace
+    this.gateway = gateway
   }
 
   @given('the `{word}` is running')
@@ -25,7 +28,7 @@ export class Components {
 
   @given('the `{word}` is running with the following manifest:')
   public async patchAndRun (name: string, yaml: string): Promise<void> {
-    const manifest = parse(yaml)
+    const manifest = parse(yaml) as object
 
     await this.runComponent(name, manifest)
   }
@@ -59,6 +62,11 @@ export class Components {
   private async runComponent (name: string, manifest?: object): Promise<void> {
     assert.ok(!(name in this.compositions), `Composition '${name}' is already running`)
 
+    // the gateway first: a component announces itself when it opens, and that only
+    // reaches a gateway that is already listening. Started the other way round, the
+    // component waits for a knock, which the request that follows does not.
+    await this.gateway.start()
+
     const path = await this.workspace.addComponent(name, manifest)
 
     this.compositions[name] = await boot.composition([path])

package/features/steps/Database.ts

@@ -32,6 +32,15 @@ export class Database {
                 : str
       }
 
+      /*
+       * A record that has never been written carries no timestamps, and the entity stamps
+       * the ones it is missing as it is read — with the time it was read. The same row then
+       * enumerates differently on every request, which is a moving `etag` and a collection
+       * that is never unmodified.
+       */
+      document._created ??= Date.now()
+      document._updated ??= document._created
+
       documents.push(document)
     }
 

package/features/steps/Gateway.ts

@@ -1,8 +1,8 @@
 import { after, afterAll, binding, given } from 'cucumber-tsflow'
 import * as boot from '@toa.io/boot'
 import { type Connector } from '@toa.io/core'
-import { parse } from '@toa.io/yaml'
-import { encode, timeout } from '@toa.io/generic'
+import { load as parse } from 'js-yaml'
+import { timeout } from '@toa.io/generic'
 import { Factory } from '../../source'
 import * as syntax from '../../source/RTD/syntax'
 import { shortcuts } from '../../source/Directive'
@@ -17,12 +17,12 @@ export class Gateway {
 
   @given('the annotation:')
   public async annotate (yaml: string): Promise<void> {
-    const annotation = parse(yaml)
+    const annotation = parse(yaml) as Partial<http.Options> & { '/'?: object }
 
-    if ('/' in annotation) {
+    if (annotation['/'] !== undefined) {
       const tree = syntax.parse(annotation['/'], shortcuts)
 
-      process.env.TOA_EXPOSITION = encode(tree)
+      process.env.TOA_EXPOSITION = JSON.stringify(tree)
     }
 
     const { debug, authorities } = annotation
@@ -34,7 +34,7 @@ export class Gateway {
     if (authorities !== undefined)
       properties.authorities = authorities
 
-    process.env.TOA_EXPOSITION_PROPERTIES = encode(properties)
+    process.env.TOA_EXPOSITION_PROPERTIES = JSON.stringify(properties)
 
     await Gateway.stop()
 
@@ -58,8 +58,8 @@ export class Gateway {
       tree.routes.push(...node.routes)
     }
 
-    process.env.TOA_EXPOSITION = encode(tree)
-    process.env.TOA_EXPOSITION_PROPERTIES = encode(DEFAULT_PROPERTIES)
+    process.env.TOA_EXPOSITION = JSON.stringify(tree)
+    process.env.TOA_EXPOSITION_PROPERTIES = JSON.stringify(DEFAULT_PROPERTIES)
 
     await Gateway.stop()
 
@@ -71,10 +71,10 @@ export class Gateway {
     const [name, namespace = 'default'] = id.split('.').reverse()
     const key = `TOA_CONFIGURATION_${namespace.toUpperCase()}_${name.toUpperCase()}`
     const def = DEFAULT_CONFIGURATION[id] ?? {}
-    const patch: object = parse(yaml)
+    const patch = parse(yaml) as object
     const configuration = Object.assign({}, def, patch)
 
-    process.env[key] = encode(configuration)
+    process.env[key] = JSON.stringify(configuration)
 
     await Gateway.stop()
 
@@ -96,7 +96,7 @@ export class Gateway {
       return
 
     process.env.TOA_EXPOSITION ??= DEFAULT_TREE
-    process.env.TOA_EXPOSITION_PROPERTIES ??= encode(DEFAULT_PROPERTIES)
+    process.env.TOA_EXPOSITION_PROPERTIES ??= JSON.stringify(DEFAULT_PROPERTIES)
 
     this.writeConfiguration()
 
@@ -136,14 +136,14 @@ export class Gateway {
       const [name, namespace = 'default'] = id.split('.').reverse()
       const key = `TOA_CONFIGURATION_${namespace.toUpperCase()}_${name.toUpperCase()}`
 
-      process.env[key] ??= encode(configuration)
+      process.env[key] ??= JSON.stringify(configuration)
     }
   }
 }
 
 const EXPOSITION = '@toa.io/extensions.exposition'
 
-const DEFAULT_TREE = encode({
+const DEFAULT_TREE = JSON.stringify({
   routes: [],
   methods: [],
   directives: [

package/features/steps/HTTP.ts

@@ -13,7 +13,6 @@ import type { Readable } from 'node:stream'
 @binding([Gateway, Parameters, Captures])
 export class HTTP extends http.Agent {
   private readonly gateway: Gateway
-  private fetched: Response | null = null
 
   public constructor (gateway: Gateway, parameters: Parameters, captures: Captures) {
     super(parameters.origin, captures)
@@ -24,7 +23,7 @@ export class HTTP extends http.Agent {
   public override async request (input: string): Promise<any> {
     await this.gateway.start()
 
-    this.fetched = await super.request(input)
+    await super.request(input)
   }
 
   @then('the following reply is sent:')
@@ -34,10 +33,9 @@ export class HTTP extends http.Agent {
 
   @then('response body contains {word}-encoded value:')
   public async bodyIs (format: string, yaml: string): Promise<void> {
-    assert.ok(this.fetched !== null, 'Response is null')
+    assert.ok(this.bytes !== null, 'Response body is not available')
 
-    const buf = await this.fetched.arrayBuffer()
-    const value = encoders[format]?.(buf as unknown as Buffer)
+    const value = encoders[format]?.(this.bytes)
     const expected = YAML.load(yaml)
 
     assert.deepEqual(value, expected, 'Values are not equal')

package/features/steps/Parameters.ts

@@ -1,7 +1,6 @@
 import { join } from 'node:path'
 import * as dotenv from 'dotenv'
 import { setDefaultTimeout } from '@cucumber/cucumber'
-import { encode } from '@toa.io/generic'
 
 dotenv.config({ path: join(__dirname, '.env') })
 
@@ -19,14 +18,14 @@ process.env.TOA_DEV = '1'
 
 // export traces to the local Tempo (`docker compose up tempo grafana`),
 // unavailability of the endpoint is harmless
-process.env.TOA_TELEMETRY_TRACES ??= encode({
+process.env.TOA_TELEMETRY_TRACES ??= JSON.stringify({
   exporters: {
     console: null,
     otlp: { endpoint: 'http://localhost:4318' }
   }
 })
 
-process.env.TOA_STORAGES = encode({
+process.env.TOA_STORAGES = JSON.stringify({
   octets: {
     provider: 'tmp',
     directory: Math.random().toString(36).substring(2)

package/features/steps/Realtime.ts

@@ -3,8 +3,8 @@ import * as assert from 'node:assert'
 import { after, binding, given, afterAll, then } from 'cucumber-tsflow'
 import { Factory } from '@toa.io/extensions.realtime'
 import * as boot from '@toa.io/boot'
-import { encode, match } from '@toa.io/generic'
-import { parse } from '@toa.io/yaml'
+import { match } from '@toa.io/generic'
+import { load as parse } from 'js-yaml'
 import { Agent } from '@toa.io/agent'
 import { Parameters } from './Parameters'
 import { Gateway } from './Gateway'
@@ -29,13 +29,13 @@ export class Realtime {
   public async start (yaml: string): Promise<void> {
     await Realtime.stop()
 
-    const annotation = parse(yaml)
+    const annotation = parse(yaml) as Record<string, string>
     const routes = []
 
     for (const [event, property] of Object.entries(annotation))
       routes.push({ event, properties: [property] })
 
-    process.env.TOA_REALTIME = encode(routes)
+    process.env.TOA_REALTIME = JSON.stringify(routes)
 
     const factory = new Factory(boot)
 

package/features/steps/Workspace.ts

@@ -1,7 +1,8 @@
 import { join } from 'node:path'
 import { tmpdir, devNull } from 'node:os'
-import { mkdtemp, cp } from 'node:fs/promises'
-import * as yaml from '@toa.io/yaml'
+import { mkdtemp, cp, readFile, writeFile } from 'node:fs/promises'
+import { load, dump } from 'js-yaml'
+import { overwrite } from '@toa.io/generic'
 
 export class Workspace {
   private root: string = devNull
@@ -35,6 +36,10 @@ export class Workspace {
   private async patchManifest (target: string, patch: object): Promise<void> {
     const path = join(target, 'manifest.toa.yaml')
 
-    await yaml.patch(path, patch)
+    const manifest = load(await readFile(path, 'utf8')) as object
+
+    overwrite(manifest, patch)
+
+    await writeFile(path, dump(manifest, { noRefs: true, lineWidth: -1 }), 'utf8')
   }
 }