@toa.io/extensions.exposition 1.0.0-alpha.250 → 1.0.0-alpha.252

package/documentation/components.md

@@ -5,6 +5,9 @@ configured in the same
 way as if they were a part of the Context. Resources exposed by the components
 are [isolated](tree.md#directives).
 
+See [Persistent credentials](credentials.md) for the centralized Basic, federation, and passkey
+management API.
+
 ## Basic credentials
 
 The `identity.basic` component stores basic credentials.

package/documentation/credentials.md

@@ -0,0 +1,85 @@
+# 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.
+
+## Federation credentials
+
+- `POST /identity/federation/:identity/` associates credentials from a trusted issuer.
+- `GET /identity/federation/:identity/` lists federation credentials.
+- `DELETE /identity/federation/:identity/:credential/` removes one federation credential.
+
+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 either listing resource. 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/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.

package/documentation/passkeys.md

@@ -2,3 +2,4 @@
 
 - [Standard](https://www.w3.org/TR/webauthn-2/)
 - [Features](../features/passkeys.feature)
+- [Credential management](credentials.md#passkeys)

package/features/credentials.feature

@@ -0,0 +1,106 @@
+@security
+Feature: Persistent credentials management
+
+  Background:
+    # developer:secret
+    Given the `identity.basic` database contains:
+      | _id                              | authority | username  | password                                                     |
+      | efe3a65ebbee47ed95a73edd911ea328 | nex       | developer | $2b$10$ZRSKkgZoGnrcTNA5w5eCcu3pxDzdTduhteVYXcp56AaNcilNkwJ.O |
+    And the `identity.federation` database contains:
+      | _id                              | authority | identity                         | iss                         | sub    | _created |
+      | fed3a65ebbee47ed95a73edd911ea328 | nex       | efe3a65ebbee47ed95a73edd911ea328 | https://accounts.google.com | google | 1000     |
+      | fed3a65ebbee47ed95a73edd911ea329 | nex       | efe3a65ebbee47ed95a73edd911ea328 | https://appleid.apple.com   | apple  | 900      |
+    And the `identity.passkeys` database contains:
+      | _id                              | authority | identity                         | kid     | aid                                  | synced | key    | counter | label           | _created |
+      | ace3a65ebbee47ed95a73edd911ea328 | nex       | efe3a65ebbee47ed95a73edd911ea328 | key-one | adce0002-35bc-c60a-648b-0b25f1f05503 | true   | cHVibGlj | 0       | Personal iPhone | 2000     |
+
+  Scenario: Listing all persistent credentials
+    When the following request is received:
+      """
+      GET /identity/credentials/efe3a65ebbee47ed95a73edd911ea328/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      authorization: Token ${{ token }}
+
+      basic:
+        username: developer
+      federation:
+        - id: fed3a65ebbee47ed95a73edd911ea328
+          iss: https://accounts.google.com
+          _created: 1000
+        - id: fed3a65ebbee47ed95a73edd911ea329
+          iss: https://appleid.apple.com
+          _created: 900
+      passkeys:
+        - id: ace3a65ebbee47ed95a73edd911ea328
+          aid: adce0002-35bc-c60a-648b-0b25f1f05503
+          synced: true
+          label: Personal iPhone
+          _created: 2000
+      """
+
+  Scenario: Deleting credentials through their components
+    When the following request is received:
+      """
+      GET /identity/credentials/efe3a65ebbee47ed95a73edd911ea328/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      authorization: Token ${{ token }}
+      """
+    When the following request is received:
+      """
+      DELETE /identity/basic/efe3a65ebbee47ed95a73edd911ea328/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Token ${{ token }}
+      """
+    Then the following reply is sent:
+      """
+      204 No Content
+      """
+    When the following request is received:
+      """
+      DELETE /identity/federation/efe3a65ebbee47ed95a73edd911ea328/fed3a65ebbee47ed95a73edd911ea328/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Token ${{ token }}
+      """
+    Then the following reply is sent:
+      """
+      204 No Content
+      """
+    When the following request is received:
+      """
+      DELETE /identity/passkeys/efe3a65ebbee47ed95a73edd911ea328/ace3a65ebbee47ed95a73edd911ea328/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Token ${{ token }}
+      """
+    Then the following reply is sent:
+      """
+      204 No Content
+      """
+    When the following request is received:
+      """
+      GET /identity/credentials/efe3a65ebbee47ed95a73edd911ea328/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Token ${{ token }}
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+
+      basic: null
+      federation:
+        - id: fed3a65ebbee47ed95a73edd911ea329
+          iss: https://appleid.apple.com
+          _created: 900
+      passkeys: []
+      """

package/features/steps/Database.ts

@@ -25,7 +25,11 @@ export class Database {
           ? int
           : str === 'null'
             ? null
-            : str
+            : str === 'true'
+              ? true
+              : str === 'false'
+                ? false
+                : str
       }
 
       documents.push(document)
@@ -62,4 +66,4 @@ export class Database {
   }
 }
 
-type Document = Record<string, string | number | null>
+type Document = Record<string, string | number | boolean | null>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/extensions.exposition",
-  "version": "1.0.0-alpha.250",
+  "version": "1.0.0-alpha.252",
   "description": "Toa Exposition",
   "author": "temich <tema.gurtovoy@gmail.com>",
   "homepage": "https://github.com/toa-io/toa#readme",
@@ -19,7 +19,7 @@
   "dependencies": {
     "@aws-sdk/protocol-http": "3.370.0",
     "@simplewebauthn/server": "13.1.1",
-    "@toa.io/core": "1.0.0-alpha.250",
+    "@toa.io/core": "1.0.0-alpha.252",
     "@toa.io/generic": "1.0.0-alpha.225",
     "@toa.io/schemas": "1.0.0-alpha.246",
     "bcryptjs": "2.4.3",
@@ -32,17 +32,18 @@
     "minimatch": "10.2.4",
     "msgpackr": "1.11.9",
     "negotiator": "1.0.0",
-    "openspan": "1.0.0-alpha.250",
+    "openspan": "1.0.0-alpha.252",
     "paseto": "3.1.4"
   },
   "scripts": {
     "test": "jest",
-    "transpile": "tsc && npm run transpile:bans && npm run transpile:basic && npm run transpile:tokens && npm run transpile:roles && npm run transpile:federation && npm run transpile:keys && npm run transpile:passkeys && npm run transpile:otp",
+    "transpile": "tsc && npm run transpile:bans && npm run transpile:basic && npm run transpile:tokens && npm run transpile:roles && npm run transpile:federation && npm run transpile:credentials && npm run transpile:keys && npm run transpile:passkeys && npm run transpile:otp",
     "transpile:bans": "tsc -p ./components/identity.bans",
     "transpile:basic": "tsc -p ./components/identity.basic",
     "transpile:tokens": "tsc -p ./components/identity.tokens",
     "transpile:roles": "tsc -p ./components/identity.roles",
     "transpile:federation": "tsc -p ./components/identity.federation",
+    "transpile:credentials": "tsc -p ./components/identity.credentials",
     "transpile:keys": "tsc -p ./components/identity.keys",
     "transpile:passkeys": "tsc -p ./components/identity.passkeys",
     "transpile:otp": "tsc -p ./components/identity.otp",
@@ -64,5 +65,5 @@
     },
     "testEnvironment": "node"
   },
-  "gitHead": "443ed152a60400ad271005fa7cf8afb101390cf0"
+  "gitHead": "753e94e44b499be02dee28fa1db2d45c053434cf"
 }