@toa.io/extensions.exposition 1.0.0-alpha.292 → 1.0.0-alpha.293

package/documentation/credentials.md

@@ -1,88 +0,0 @@
-# Persistent credentials
-
-Persistent credentials associate an [Identity](identity.md) with a reusable authentication method.
-Exposition stores Basic, OpenID Connect federation, and WebAuthn passkey credentials. Local tokens
-and one-time passwords are not persistent credentials: tokens are stateless and OTP records expire.
-
-See [Features](../features/credentials.feature).
-
-## Listing credentials
-
-`GET /identity/credentials/:identity/` returns all persistent credentials associated with the
-Identity in the current authority. Access requires credentials of that Identity.
-
-```http
-GET /identity/credentials/fc8e66ddd51d45eea89602c9dd38a542/ HTTP/1.1
-authorization: Token ...
-accept: application/yaml
-```
-
-```yaml
-basic:
-  username: user@example.com
-federation:
-  - id: 09200d0bcc2448c5863e3f50ae18af84
-    iss: https://accounts.google.com
-    CREATED: 1754899200000
-passkeys:
-  - id: 54ed430804324e81b39756ea4708b546
-    aid: adce0002-35bc-c60a-648b-0b25f1f05503
-    synced: true
-    label: Personal iPhone
-    CREATED: 1754899200000
-```
-
-`basic` is `null` when Basic credentials do not exist. `federation` and `passkeys` are always
-arrays. Secret and authentication data, including password hashes, federation subjects, public
-keys, signature counters, and transports, are not returned.
-
-The federation issuer identifies the provider. For example, Google uses
-`https://accounts.google.com` and Apple uses `https://appleid.apple.com`. Applications should map
-trusted issuers to their own provider names and presentation.
-
-The passkey `aid` is its
-[AAGUID](https://www.w3.org/TR/webauthn-2/#aaguid), which can be resolved against an authenticator
-metadata catalog. `synced` indicates whether the credential was backed up and is therefore likely
-available on more than one device.
-
-## Basic credentials
-
-- `POST /identity/basic/:identity/` adds Basic credentials to an Identity.
-- `PATCH /identity/basic/:identity/` changes its username or password.
-- `DELETE /identity/basic/:identity/` removes its Basic credentials.
-
-An Identity can have at most one Basic credential in an authority. See
-[Basic credentials configuration](components.md#basic-credentials) for password hashing,
-constraints, and principal configuration.
-
-## Federated credentials
-
-- `POST /identity/federation/:identity/` associates credentials from a trusted issuer and returns
-  the associated credential as it is listed.
-- `GET /identity/federation/:identity/` lists federated credentials.
-- `DELETE /identity/federation/:identity/:credential/` removes one federated credential.
-
-If the credentials are already associated with the Identity, the existing credential is returned.
-
-An Identity can have credentials from multiple issuers and can have multiple subjects from the
-same issuer. The `:credential` segment is the `id` returned by any of these resources. Federation
-resources are provider-independent; issuer-specific authorization flows remain the responsibility
-of the application.
-
-## Passkeys
-
-Passkey registration consists of a challenge followed by credential creation:
-
-- `POST /identity/passkeys/challenges/:identity/` creates a registration challenge.
-- `POST /identity/passkeys/:identity/` verifies the response and stores the passkey.
-- `GET /identity/passkeys/:identity/` lists passkeys.
-- `DELETE /identity/passkeys/:identity/:credential/` removes one passkey.
-
-See [Web Authentication](passkeys.md) for standards and feature scenarios.
-
-## Removing the last credential
-
-Credential components intentionally do not coordinate with one another. Consequently, credentials
-can be removed without checking whether another persistent credential exists.
-Applications that require a recoverable login must prevent removal of the last usable credential
-in their client workflow.

package/documentation/dev.md

@@ -1,30 +0,0 @@
-# Development tools
-
-## `dev:stub`
-
-Returns a successful response with the given body.
-
-```yaml
-/foo:
-  dev:sub: Hello!
-/bar:
-  dev:sub:
-    hello: world
-```
-
-## `dev:sleep`
-
-Enables random delay before processing the request, up to given maximum time in milliseconds.
-
-Desired delay range can be set in the `sleep` request header as a JSON array of two numbers, the minimum
-and maximum delay in milliseconds.
-
-```yaml
-/foo:
-  dev:sleep: 1000
-```
-
-```http
-GET /foo/ HTTP/1.1
-sleep: [500, 1000]
-```

package/documentation/discovery.md

@@ -1,81 +0,0 @@
-# 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

@@ -1,44 +0,0 @@
-# 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

@@ -1,122 +0,0 @@
-# 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

@@ -1,304 +0,0 @@
-# Identity
-
-Identity is the fundamental entity within an authentication system that represents the **unique
-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.
-Once the last credentials are removed from the Identity, it ceases to exist.
-Without credentials, there is no basis for defining or asserting an Identity.
-
-## Authentication
-
-The Authentication system resolves provided credentials to an Identity using one of the supported
-authentication schemes.
-
-The Authentication is request-agnostic, meaning it does not depend on the specific URL being
-requested or the content of the request body.
-The only information it handles is the value of the `Authorization` header.
-
-> Except for its own [management resources](components.md).
-
-If the provided credentials are not valid or not associated with an Identity, then Authentication
-interrupts request processing and responds with an authentication error.
-
-### Basic scheme
-
-Classic username/password pair. See [RFC7617](https://datatracker.ietf.org/doc/html/rfc7617).
-
-```http
-Authorization: Basic aGVsbG86d29ybGQK
-```
-
-See [`identity.basic` component](components.md#basic-credentials).
-
-### Token scheme
-
-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
-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
-subsequent requests.
-
-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, 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).
-
-```http
-Authorization: Bearer eyJhbGciOiJIUzI1...
-```
-
-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
-
-configuration:
-  identity.federation:
-    trust:
-      - iss: https://accounts.google.com
-        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.
-
-```yaml
-# context.toa.yaml
-configuration:
-  identity.otp:
-    lifetime: 60 # seconds
-    attempts: 5
-```
-
-## Identity inception
-
-The simplest way to establish a relationship between an Identity and an entity representing a user
-is to synchronize their identifiers.
-
-This can be achieved by using the `auth:incept` directive as follows:
-
-```yaml
-# manifest.toa.yaml
-name: users
-
-entity:
-  properties:
-    name:
-      type: string
-
-exposition:
-  /:
-    POST:
-      incept: id
-      endpoint: transit
-```
-
-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 may contain (non-existent) credentials that will be associated
-with the created Identity.
-
-```http
-POST /users/
-authorization: Basic dXNlcjpwYXNz
-accept: application/yaml
-content-type: application/yaml
-
-name: John
-```
-
-```
-201 Created
-content-type: application/yaml
-
-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>
-<dt>How can I log in a user?</dt>
-<dd>
-Technically speaking, since the Authentication is request-agnostic, user credentials
-can be sent with any request.
-
-However, it is most likely that a request originator will need to obtain an Identity value for
-subsequent requests.
-For this reason, it is recommended to make a `GET /identity/` request.
-</dd>
-<dt>How can I log out a user?</dt>
-<dd>Delete <code>Token</code> credentials from the device.</dd>
-<dt>Where are the sessions?</dt>
-<dd>
-The Authentication is stateless, meaning it does not store any information between
-requests except for persistent credentials.</dd>
-<dt>How can I pass the Identity to an operation call?</dt>
-<dd>
-This is not possible. Refer to the Resource Design Guidelines for more information.
-<a href="https://github.com/toa-io/toa/issues/353">#353</a>
-</dd>
-</dl>