@toa.io/extensions.exposition 1.0.0-alpha.29 → 1.0.0-alpha.291

package/documentation/discovery.md

@@ -0,0 +1,81 @@
+# Resource discovery
+
+Everything an application serves, at one path, and a page to read it with.
+
+```http
+OPTIONS /.discovery HTTP/1.1
+accept: application/yaml
+```
+
+```http
+200 OK
+Allow: GET, HEAD, OPTIONS
+cache-control: private, max-age=1800
+
+routes:
+  /pots:
+    title: Pots
+    GET:
+      title: Every pot
+      description: Every pot there is, newest first.
+      output:
+        type: array
+        items:
+          type: object
+          properties:
+            title: { type: string, maxLength: 64 }
+    POST:
+      input:
+        type: object
+        properties:
+          title: { type: string, maxLength: 64 }
+        required: [title]
+      errors:
+        - NO_WAY
+  /pots/:id:
+    protected: true
+    GET:
+      protected: true
+      route:
+        id: { title: Which pot }
+```
+
+`routes` is keyed by route template, and an object so that what is said of the whole tree has
+somewhere to go. What a key maps to is what [`OPTIONS`](introspection.md) on that path
+answers — what the resource is, from [`help:node`](help.md), beside every method of it — so a key
+can be read from here and sent straight back as a request. A method this identity may not reach is
+not in either, and a resource they may reach no method of is not here at all — so what a reader
+sees is what they may call, and signing in is what adds to it.
+
+A key carries no trailing slash, and a request needs one: `OPTIONS /pots/:id` and
+`OPTIONS /pots/:id/` both answer, but `GET /pots/:id` is `404` and `GET /pots/:id/` is the call.
+Append it.
+
+Held for half an hour, and `private`: what is in it is what the identity that asked may reach.
+
+## The page
+
+`GET /.discovery/` is a page that reads the tree, served from the same origin the API is. It
+answers before a credential is read, so it opens for a client whose token has expired — which is
+the client most likely to be looking.
+
+A method is called from it: the verb is a button, what the method takes is a form, and what came
+back is shown where the form was. The call is made as whoever is reading — the same request they
+would send themselves, and with the same effect.
+
+A `GET /` is sent here where its `accept` prefers a page, or asks for nothing in particular — so
+the address of the application opens it in a browser, and a link to that address unfurls as it.
+A client that asked for a media type the gateway answers with gets what it asked for, and a route
+declared at `/` answers `/` as it always did.
+
+## Turning it off
+
+Both answer wherever a gateway does, and no annotation turns either on. An application that does
+not publish its routes to everyone refuses `/.discovery` at the ingress, which is the whole of
+what an operator does about it.
+
+## References
+
+- [Introspection](introspection.md), which is what an entry is
+- [Help](help.md), which is what names one
+- [Features](../features/discovery.feature)

package/documentation/flow.md

@@ -0,0 +1,44 @@
+# Request flow
+
+## `flow:fetch`
+
+Fetches the content from the resource returned by the specified endpoint.
+
+The value of the directive is a `string` specifying endpoint to be called for the redirection
+request.
+
+Request `authority`, `path` and `parameters` are passed as input to the redirection endpoint,
+and it must return a URL `string`, an `Error` or an object with the following properties:
+
+```yaml
+url: string
+options?:
+  method?: string
+  headers?: Record<string, string>
+  body?: string
+```
+
+If it returns a URL or Request, then the response to the specified request is returned as the
+response to the original request, along with the `content-type`, `content-length`, and `etag`
+headers.
+
+## `flow:compose`
+
+Compose an object from a response stream in object mode.
+
+The value of the directive is an object whose values are JavaScript expressions
+accessing the response stream objects composed into an array named `$`.
+
+```yaml
+flow:compose:
+  one: $[0].status
+  two: $[1].data.foo
+  three: $[2].amount
+```
+
+```yaml
+flow:compose:
+  sum: $[0].value + $[1].value
+```
+
+Be careful.

package/documentation/help.md

@@ -0,0 +1,122 @@
+# Help
+
+What a resource and its methods are, in the words an application chooses for them. One
+declaration, read by everything that describes a resource: [`OPTIONS`](introspection.md),
+[discovery](discovery.md), and the tools [MCP](mcp.md) publishes.
+
+```yaml
+/pots:
+  help:node: Pots
+  GET:
+    help:method: Every pot
+    help:query:
+      criteria:
+        title: What to match
+        description: An RSQL expression over a pot's fields.
+    endpoint: enumerate
+  /:id:
+    GET:
+      help:method:
+        title: One pot
+        description: The pot by its id, and what is in it.
+      help:route:
+        id: Which pot
+      endpoint: observe
+```
+
+<dl>
+<dt><code>help:node</code></dt>
+<dd>What the resource is.</dd>
+<dt><code>help:method</code></dt>
+<dd>What one of its methods is.</dd>
+<dt><code>help:route</code></dt>
+<dd>What a route variable is, by the name the template gives it.</dd>
+<dt><code>help:query</code></dt>
+<dd>What a querystring parameter is, by name.</dd>
+</dl>
+
+All four take the same value. A bare one is the <code>title</code> — the short thing, and what a
+client has somewhere to put. A sentence is written as a <code>description</code> beside it, and
+either may stand alone. The parameters name each one they describe.
+
+`help:method: null` hides the method instead of naming it: it is in no answer — not `OPTIONS`,
+not the [tree](discovery.md), not the tools [MCP](mcp.md) publishes — and is reached exactly as
+it was. What a monitor calls, and what a person has no business going looking for, is declared
+this way. A resource whose every method is hidden answers `403` to `OPTIONS` and is not in the
+tree at all.
+
+```yaml
+/hello/agent:
+  GET:
+    help:method: null
+    endpoint: agent
+```
+
+A title is not a name. A name is an address — `apps._identity._id.repos.POST` — and reads as one;
+this is what a person is shown instead.
+
+An operation [states what it is](/documentation/component/declaration.md) as well, and that is not
+this: it is written without knowledge of any route, and a method is an operation and a route
+together. The same operation mounted twice is two methods, and one sentence is not true of both.
+The operation's own is the Introspection's to read, and the gateway does not use it.
+
+## Where it is answered
+
+`help:node` is answered beside the methods, and `help:method` inside the method it is on. A verb
+is upper case, so neither key can be mistaken for the other. A parameter's goes in its schema,
+which is where a schema says these anyway:
+
+```yaml
+title: Pots
+GET:
+  title: Every pot
+  query:
+    criteria:
+      type: string
+      title: What to match
+      description: An RSQL expression over a pot's fields.
+```
+
+Describe a parameter by the name the answer carries it under. `map:segments` answers a variable
+under the property it fills, so that is its name here and the template's is nowhere in the answer.
+
+A route variable the template names is answered whether or not the operation declares it — an `:id`
+an observation takes through the query is otherwise not in the answer at all, and describing it is
+what puts it there. Anything else is described only where it is already answered. A name that is
+nobody's is not answered, and nothing here checks one: the template does not say them all.
+
+`help:query` describes the [parameters a resource declares](query.md#parameters). What selects
+records — `criteria`, `sort` and the rest — is the same of every queryable resource and says so
+itself, so it is neither answered here nor described.
+
+## Where it applies
+
+To the node it is written on, and to nothing under it. Every other directive applies downward;
+carried down, this one would say of every resource below that it is the one it was written for.
+
+```yaml
+/pots:
+  help:node: Pots      # `/pots`, and not `/pots/:id`
+  GET: enumerate
+  /:id:
+    GET: observe
+```
+
+A node whose `/` answers in its place is the exception, because the two are one resource:
+
+```yaml
+/pots:
+  help:node: Pots      # `/pots/` is what answers, and it is described
+  /:
+    GET: enumerate
+```
+
+A resource is described beside what it serves, so a node that serves nothing cannot be described.
+Declaring it there is refused where it is written, rather than found missing from the answer.
+
+## References
+
+- [Resource introspection](introspection.md), which is where a method's own is answered
+- [Resource discovery](discovery.md), which answers every resource at once
+- [MCP](mcp.md), where a published method is a tool called this
+- [Features](../features/help.feature)

package/documentation/identity.md

@@ -6,6 +6,9 @@ identifier** of an individual, organization, application or device.
 To prove its Identity, the request originator must provide a valid _credentials_ that are associated
 with that Identity.
 
+Persistent authentication methods and their management resources are described in
+[Persistent credentials](credentials.md).
+
 Identity is intrinsically linked to credentials, as an Identity is established only when the first
 set of credentials for that Identity is created.
 In other words, the creation of credentials marks the inception of an Identity.
@@ -38,23 +41,51 @@ See [`identity.basic` component](components.md#basic-credentials).
 
 ### Token scheme
 
-Tokens issued by the Authentication system. These tokens are [PASETO](https://paseto.io).
+Tokens issued by the Authentication system. New tokens are compact
+[JSON Web Encryption (JWE)](https://www.rfc-editor.org/rfc/rfc7516) values using direct symmetric
+encryption (`alg: dir`) and AES-256-GCM (`enc: A256GCM`). Legacy PASETO V3.local tokens remain
+accepted during migration and are always replaced on successful authentication.
 
 ```http
-Authrization: Token v4.local.eyJzdWIiOiJqb2hu...
+Authorization: Token eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2R0NNIiwidHlwIjoiSldUIiwia2lkIjo...
 ```
 
 The `Token` is the **primary** authentication scheme.
 If request originators use an alternative authentication scheme, they will receive a response
-containing `Token`credentials and will be required to switch to the `Token` scheme for any
+containing `Token` credentials and will be required to switch to the `Token` scheme for any
 subsequent requests.
-Continued use of other authentication schemes will result in temporary blocking of requests.
 
-See [`identity.tokens` component](components.md#stateless-tokens).
+See [`identity.tokens` component](components.md#local-tokens).
+
+### Failed authentications
+
+Credentials that are rejected can be metered per client address, whatever the scheme. An address
+may fail `attempts` at once and earns them back at `attempts` per `interval` seconds; a request
+carrying credentials from an address with nothing left is answered `429 Too Many Requests` with
+`Retry-After`. Nothing is metered unless the exposition annotation carries `bouncer`;
+`attempts` and `interval` default to 20 and 60. The address is the one the request context
+resolved, see [Client address](ip.md): `bouncer` requires `ip`, in the same environment, and a
+request without an address is not metered.
+
+```yaml
+# context.toa.yaml
+
+exposition:
+  ip: cf-connecting-ip
+  bouncer:
+    attempts: 20
+    interval: 60
+```
+
+The count is shared by the gateway replicas through
+[atomicity](../../../connectors/atomicity/readme.md) and decided in each process; nothing is read on
+the request path.
 
 ### Bearer scheme
 
-OpenID tokens issued by trusted providers.
+OpenID tokens issued by trusted providers, and access tokens issued by
+[this authorization server](oauth.md) to OAuth clients. Both are presented the same way, and each
+provider says which credentials are its own; a credential neither claims is refused.
 For more information, refer
 to [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html),
 [RFC6750](https://datatracker.ietf.org/doc/html/rfc6750).
@@ -63,8 +94,8 @@ to [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.ht
 Authorization: Bearer eyJhbGciOiJIUzI1...
 ```
 
-Trusted providers are specified using the `identity.federation` property within the configuration
-annotation.
+Trusted providers are specified using the `identity.federation` configuration. Provider metadata
+and signing keys are discovered using OpenID Connect discovery and JWKS.
 
 ```yaml
 # context.toa.yaml
@@ -73,16 +104,97 @@ configuration:
   identity.federation:
     trust:
       - iss: https://accounts.google.com
-        aud:
-          - <GOOGLE_CLIENT_ID>
+        aud: <GOOGLE_CLIENT_ID>
+
+      - iss: https://appleid.apple.com
+        aud: <APPLE_CLIENT_ID>
+        secret: <APPLE_CLIENT_SECRET> # enables Authorization Code Flow
+    principal:
+      authority: example
+      iss: https://accounts.google.com
+      sub: 4218230498234
+    assert: true
+```
+
+`principal` specifies the authority and the values of the `iss` and `sub` claims of an Identity
+that will be granted with a `system` role. The same subject in another authority is ordinary
+credentials.
+
+`assert` indicates whether the Identity should be implicitly created when valid credentials for a
+non-existent Identity are provided (default `true`).
+
+### Authorization Code Flow
 
+[OAuth 2.0 RFC 6749, section 4.1](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1)
+
+```
+GET /identity/
+authorization: Code <credentials>
+```
+
+`<credentials>` is a base64-encoded JSON containing the following properties:
+
+```yaml
+code: authorization code
+iss: code issuer
+for: redirect URI
+```
+
+Trust configuration for the issuer requires either `secret` or `signature`
+to enable the Authorization Code Flow.
+
+> If `aud` is an array, the first value is used.
+
+```yaml
+# context.toa.yaml
+configuration:
+  identity.federation:
+    trust:
+      - iss: https://accounts.google.com
+        aud: 1045282659797-n705sf85j4b2rodtpdn43od43tvseiet.apps.googleusercontent.com
+        secret: $GOOGLE_CLIENT_SECRET
       - iss: https://appleid.apple.com
+        aud: io.toa.services.id
+        signature:
+          iss: team-id
+          kid: key-id
+          key: $APPLE_PRIVATE_KEY # PKCS8 PEM, as in the .p8 file
+```
+
+### OTP scheme
+
+One-time passwords.
+
+Passwords can be issued by calling `identity.otp.issue` operation, with the following input:
+
+```yaml
+authority: string
+username: string
+```
+
+The reply will contain the `code` property of type `string` formed as a random 6-digit number,
+valid for 60 seconds by default.
+
+```yaml
+code: 123456
+```
+
+OTP can be used with `OTP` authentication formatted as `base64(username:password)`.
+
+```
+GET /identity/ HTTP/1.1
+authentication: OTP dXNlcm5hbWU6MTIzNDU2
+```
+
+OTP expiration time and the number of failed attempts a username is allowed within it can be
+configured using the `identity.otp` configuration.
 
-      - iss: private.entity
-        secrets:
-          HS384:
-            key0: <THE-SECRET-STRING-FOR-HS384>
-            key1: <THE-SECRET-STRING-FOR-HS384> # selected by `kid` in the JWT header
+```yaml
+# context.toa.yaml
+configuration:
+  identity.otp:
+    lifetime: 60 # seconds
+    attempts: 5
 ```
 
 ## Identity inception
@@ -97,8 +209,9 @@ This can be achieved by using the `auth:incept` directive as follows:
 name: users
 
 entity:
-  schema:
-    name: string
+  properties:
+    name:
+      type: string
 
 exposition:
   /:
@@ -110,7 +223,7 @@ exposition:
 The value of the `auth:incept` directive refers to the name of the response property that will be
 returned by the `POST` operation, containing the created entity identifier.
 
-A request with Identity inception must contain (non-existent) credentials that will be associated
+A request with Identity inception may contain (non-existent) credentials that will be associated
 with the created Identity.
 
 ```http
@@ -132,6 +245,39 @@ id: 2428c31ecb6e4a51a24ef52f0c4181b9
 As a result of processing the above request, the provided Basic credentials associated with the
 Identity `2428c31ecb6e4a51a24ef52f0c4181b9` are created.
 
+> `auth:incept` directive may have a `null` value, which means that the Identity will be created
+> without any associated entity.
+
+Inception is supported for `Basic` and `Bearer` authentication schemes.
+
+Inception goes ahead when the request carries no credentials, or credentials the scheme verified
+and no Identity owns, which its `authenticate` operation reports as `NOT_FOUND`. Credentials
+rejected for any other reason, a wrong password for one, are answered with `401 Unauthorized`
+before the endpoint is called.
+
+## Identity assertion
+
+`auth:assert` directive is used to ensure that given credentials are associated with an existing
+Identity or to create a new Identity if it does not exist.
+The directive itself does not allow or deny access to the requested resource.
+
+> Used authentication scheme must support inception.
+
+```yaml
+/accounts/echo:
+  auth:assert: true
+  auth:anyone: true
+  endpoint: echo
+```
+
+```http
+GET /accounts/echo/
+authorization: Basic new-or-existent-credentials
+```
+
+If new Identity is created and endpoint returns a successful response, the status code `201 Created`
+is returned.
+
 ## FAQ
 
 <dl>

package/documentation/introspection.md

@@ -0,0 +1,123 @@
+# Resource introspection
+
+Any resource can be introspected by sending an `OPTIONS` request to the resource's path.
+[Resource discovery](discovery.md) answers every resource at once, at `OPTIONS /.discovery`, and
+serves a page that reads it.
+
+What it answers is what the route's directives leave of what the operation declared, for each
+method this identity may reach. A method they may not is not there, nor in `Allow`; a resource
+whose every method they may not reach is `403`.
+
+A credential does not narrow it. What refuses one at an [`anonymous`](access.md#anonymous) route
+is about a reply a cache would hold, and a description is not one — so a route that is public is
+described to whoever asks, as it is at `/.rpc` and `/.mcp`.
+
+What the resource itself is, from [`help:node`](help.md), is answered beside the methods rather
+than inside one. A verb is upper case, so neither key can be mistaken for the other. A resource
+carries `private`, `protected` and `system` where any of its methods does. A method
+[`help:method: null`](help.md) hides is in none of this, and is reached as it always was.
+
+Introspection properties:
+
+- `title` and `description` what the route states this method is, from
+  [`help:method`](help.md). The operation states what it is too, and that is not this: it is
+  written without knowledge of any route, and the same operation mounted twice is two methods
+- `anonymous` reaching it takes nothing — [`auth:anonymous`](access.md#anonymous). Said rather
+  than left unsaid, because it is also what refuses a caller presenting a credential: a client
+  holding one has to know which methods not to present it to
+- `authenticated` reaching it takes being someone, whoever — [`auth:anyone`](access.md#anyone),
+  `auth:delegate` and `auth:claims`
+- `private` reaching it is being the identity it is about — [`auth:id`](access.md#id)
+- `protected` reaching it takes a role — [`auth:role`](access.md#role)
+- `system` and that role is one of the `system` scope, which guards what an application runs
+  on rather than what it serves
+- `route` route parameters, including what `map:segments` names differently, each as
+  [`help:route`](help.md) describes it
+- `query` the [query parameters](query.md#parameters) this resource declares, each as
+  [`help:query`](help.md) describes it. What selects records — `criteria`, `sort`, `limit`,
+  `omit`, `search` — is not among them: it is the same of every queryable resource, and so
+  not something one says about itself. A [procedure](rpc.md) carries it, because there it is
+  something the caller sends
+- `octets` what sending a file takes, from [`octets:put`](octets.md): the media types it
+  `accept`s, the `limit` a larger body is refused by, and `stream` where storing it starts a
+  workflow and the reply arrives in parts rather than as one object
+- `input` input schema, restricted by `io:input`, without what the gateway fills itself
+- `output` output schema, restricted by `io:output`; absent where the reply is not sent at all.
+  An operation that declares none is described by what its type answers: a transition, an
+  observation and an assignment work on the Entity Object, so that is what they are said to
+  answer — a set of them where the scope is a set. A computation neither uses the scope nor
+  produces one, and an effect answers whatever it computed, so neither is guessed at. It is a
+  description and nothing is held to it — an operation answering a projection says so by
+  declaring its own `output`
+- `errors` error codes
+
+```http
+OPTIONS /pots/:id/ HTTP/1.1
+accept: application/yaml
+```
+
+```http
+200 OK
+Allow: GET, POST
+
+GET:
+  description: Every pot there is, newest first.
+  route:
+    id:
+      type: string
+      pattern: ^[a-fA-F0-9]{32}$
+  output:
+    type: array
+    items:
+      type: object
+      properties:
+        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:
+  route:
+    id:
+      type: string
+      pattern: ^[a-fA-F0-9]{32}$
+  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
+    required:
+      - title
+      - volume
+  output:
+    type: object
+    properties:
+      id:
+        type: string
+        pattern: ^[a-fA-F0-9]{32}$
+    additionalProperties: false
+  errors:
+    - NO_WAY
+    - WONT_CREATE
+```