From c04c1671630491d3d44dd456aebf22b9d1dc64c1 Mon Sep 17 00:00:00 2001 From: Blair Currey <12960453+BlairCurrey@users.noreply.github.com> Date: Mon, 26 Jan 2026 13:01:12 -0500 Subject: [PATCH 1/5] feat: directed identity --- VERSION | 2 +- openapi/auth-server.yaml | 90 +++++++++++++++++++++++++++++- openapi/resource-server.yaml | 2 +- openapi/wallet-address-server.yaml | 2 +- 4 files changed, 90 insertions(+), 6 deletions(-) diff --git a/VERSION b/VERSION index 867e524..589268e 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -1.2.0 \ No newline at end of file +1.3.0 \ No newline at end of file diff --git a/openapi/auth-server.yaml b/openapi/auth-server.yaml index d6cd3cd..2d9342d 100644 --- a/openapi/auth-server.yaml +++ b/openapi/auth-server.yaml @@ -1,7 +1,7 @@ openapi: 3.1.0 info: title: Open Payments Authorization Server - version: '1.2.0' + version: '1.3.0' license: name: Apache 2.0 identifier: Apache-2.0 @@ -164,6 +164,23 @@ paths: - read identifier: 'http://ilp.interledger-test.dev/bob' client: 'https://webmonize.com/.well-known/pay' + Grant request with directed identity (JWK): + value: + access_token: + access: + - type: incoming-payment + actions: + - create + - read + identifier: 'http://ilp.interledger-test.dev/bob' + client: + jwk: + kid: example-key-1 + alg: EdDSA + use: sig + kty: OKP + crv: Ed25519 + x: 11qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPcHURo Grant request for subject information: value: subject: @@ -565,15 +582,42 @@ components: additionalProperties: false client: title: client - type: string description: |- - Wallet address of the client instance that is making this request. + Client identification for grant requests. When sending a non-continuation request to the AS, the client instance MUST identify itself by including the client field of the request and by signing the request. + Can be either: + - A wallet address string (backwards compatible format) + - An object with either `jwk` (for directed identity) or `walletAddress` (mutually exclusive) + + When using a wallet address string or the `walletAddress` property: A JSON Web Key Set document, including the public key that the client instance will use to protect this request and any continuation requests at the AS and any user-facing information about the client instance used in interactions, MUST be available at the wallet address + `/jwks.json` url. + When using the `jwk` property (directed identity approach): + The client instance provides its public key directly in the request, eliminating the need for the AS to fetch it from a wallet address. This approach enhances privacy by not requiring the client to expose a persistent wallet address identifier. + If sending a grant initiation request that requires RO interaction, the wallet address MUST serve necessary client display information. + oneOf: + - type: string + format: uri + description: 'DEPRECATED: This string format of the client wallet address is maintained only for backwards compatibility. Migrate to the object form with `jwk` or `walletAddress`.' + deprecated: true + - type: object + description: Client identification object with either a JWK (for directed identity) or wallet address. + properties: + walletAddress: + type: string + format: uri + description: Wallet address of the client instance that is making this request. + jwk: + $ref: '#/components/schemas/json-web-key' + oneOf: + - required: + - walletAddress + - required: + - jwk + additionalProperties: false continue: title: continue type: object @@ -783,6 +827,46 @@ components: maxItems: 1 required: - sub_ids + json-web-key: + type: object + properties: + kid: + type: string + alg: + type: string + description: 'The cryptographic algorithm family used with the key. The only allowed value is `EdDSA`. ' + enum: + - EdDSA + use: + type: string + enum: + - sig + kty: + type: string + enum: + - OKP + crv: + type: string + enum: + - Ed25519 + x: + type: string + pattern: '^[a-zA-Z0-9-_]+$' + description: The base64 url-encoded public key. + required: + - kid + - alg + - kty + - crv + - x + title: Ed25519 Public Key + description: A JWK representation of an Ed25519 Public Key + examples: + - kid: key-1 + use: sig + kty: OKP + crv: Ed25519 + x: 11qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPcHURo securitySchemes: GNAP: name: Authorization diff --git a/openapi/resource-server.yaml b/openapi/resource-server.yaml index 0366d55..a571244 100644 --- a/openapi/resource-server.yaml +++ b/openapi/resource-server.yaml @@ -1,7 +1,7 @@ openapi: 3.1.0 info: title: Open Payments - version: '1.2.0' + version: '1.3.0' license: name: Apache 2.0 identifier: Apache-2.0 diff --git a/openapi/wallet-address-server.yaml b/openapi/wallet-address-server.yaml index e78497b..bffa697 100644 --- a/openapi/wallet-address-server.yaml +++ b/openapi/wallet-address-server.yaml @@ -1,7 +1,7 @@ openapi: 3.1.0 info: title: Wallet Address API - version: '1.2.0' + version: '1.3.0' license: name: Apache 2.0 identifier: Apache-2.0 From d4d6a02495ea90b5e8c56cb9f1bbd335688543b5 Mon Sep 17 00:00:00 2001 From: Blair Currey <12960453+BlairCurrey@users.noreply.github.com> Date: Tue, 27 Jan 2026 10:03:05 -0500 Subject: [PATCH 2/5] Update openapi/auth-server.yaml Co-authored-by: Radu-Cristian Popa --- openapi/auth-server.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/openapi/auth-server.yaml b/openapi/auth-server.yaml index 2d9342d..119cc6b 100644 --- a/openapi/auth-server.yaml +++ b/openapi/auth-server.yaml @@ -863,6 +863,7 @@ components: description: A JWK representation of an Ed25519 Public Key examples: - kid: key-1 + alg: EdDSA use: sig kty: OKP crv: Ed25519 From 02ab4cf98c2e88b11b6ff9c6f02b6772a7e667ee Mon Sep 17 00:00:00 2001 From: Blair Currey <12960453+BlairCurrey@users.noreply.github.com> Date: Tue, 27 Jan 2026 10:03:11 -0500 Subject: [PATCH 3/5] Update openapi/auth-server.yaml Co-authored-by: Radu-Cristian Popa --- openapi/auth-server.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/openapi/auth-server.yaml b/openapi/auth-server.yaml index 119cc6b..3de867e 100644 --- a/openapi/auth-server.yaml +++ b/openapi/auth-server.yaml @@ -846,6 +846,7 @@ components: enum: - OKP crv: + description: 'The cryptographic curve used with the key. This parameter identifies the elliptic curve (for EC keys) or the Edwards curve (for OKP keys). The only allowed value is `Ed25519`.' type: string enum: - Ed25519 From dffb4c015d479fa14b0b692e372f73ad8d24d1fb Mon Sep 17 00:00:00 2001 From: Blair Currey <12960453+BlairCurrey@users.noreply.github.com> Date: Tue, 27 Jan 2026 10:03:18 -0500 Subject: [PATCH 4/5] Update openapi/auth-server.yaml Co-authored-by: Radu-Cristian Popa --- openapi/auth-server.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openapi/auth-server.yaml b/openapi/auth-server.yaml index 3de867e..b6ea8fa 100644 --- a/openapi/auth-server.yaml +++ b/openapi/auth-server.yaml @@ -595,7 +595,7 @@ components: A JSON Web Key Set document, including the public key that the client instance will use to protect this request and any continuation requests at the AS and any user-facing information about the client instance used in interactions, MUST be available at the wallet address + `/jwks.json` url. When using the `jwk` property (directed identity approach): - The client instance provides its public key directly in the request, eliminating the need for the AS to fetch it from a wallet address. This approach enhances privacy by not requiring the client to expose a persistent wallet address identifier. + The client instance provides its public key directly in the request, eliminating the need for the AS to fetch it from a wallet address. This approach enhances privacy by not requiring the client to expose a persistent wallet address identifier. The `jwk` property can only be used for non-interactive grant requests (i.e.: incoming payments). If sending a grant initiation request that requires RO interaction, the wallet address MUST serve necessary client display information. oneOf: From 6f57946967d929651770380884f559f813773c12 Mon Sep 17 00:00:00 2001 From: Blair Currey <12960453+BlairCurrey@users.noreply.github.com> Date: Tue, 27 Jan 2026 12:57:06 -0500 Subject: [PATCH 5/5] refactor: friendlier mutual exclusivity --- openapi/auth-server.yaml | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/openapi/auth-server.yaml b/openapi/auth-server.yaml index b6ea8fa..c9f97c4 100644 --- a/openapi/auth-server.yaml +++ b/openapi/auth-server.yaml @@ -604,19 +604,18 @@ components: description: 'DEPRECATED: This string format of the client wallet address is maintained only for backwards compatibility. Migrate to the object form with `jwk` or `walletAddress`.' deprecated: true - type: object - description: Client identification object with either a JWK (for directed identity) or wallet address. + required: [walletAddress] properties: walletAddress: type: string format: uri description: Wallet address of the client instance that is making this request. + additionalProperties: false + - type: object + required: [jwk] + properties: jwk: $ref: '#/components/schemas/json-web-key' - oneOf: - - required: - - walletAddress - - required: - - jwk additionalProperties: false continue: title: continue