From d1a66ab9a5d3729d6525b9f20c4fbdfb8ad8907e Mon Sep 17 00:00:00 2001 From: Tyler Leonhardt Date: Fri, 13 Nov 2026 13:40:40 -0800 Subject: [PATCH] auth: add optional account label Extend authenticate with an optional display-only accountLabel alongside the accountId introduced in #583. Regenerate native models and schemas, document compatibility, and cover the field in schema validation and shared round-trip fixtures. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../Generated/Commands.generated.cs | 7 ++++++ clients/go/ahptypes/commands.generated.go | 5 +++++ .../generated/Commands.generated.kt | 9 +++++++- clients/rust/crates/ahp-types/src/commands.rs | 6 +++++ .../Generated/Commands.generated.swift | 10 ++++++++- .../20261113-authenticate-account-label.json | 4 ++++ docs/specification/authentication.md | 9 +++++++- schema/commands.schema.json | 4 ++++ schema/errors.schema.json | 4 ++++ scripts/generate-json-schema.test.ts | 21 ++++++++++++++++++ types/common/commands.ts | 7 ++++++ .../094-authenticate-account-label.json | 22 +++++++++++++++++++ 12 files changed, 105 insertions(+), 3 deletions(-) create mode 100644 docs/.changes/20261113-authenticate-account-label.json create mode 100644 types/test-cases/round-trips/094-authenticate-account-label.json diff --git a/clients/dotnet/src/AgentHostProtocol.Abstractions/Generated/Commands.generated.cs b/clients/dotnet/src/AgentHostProtocol.Abstractions/Generated/Commands.generated.cs index 0b4e87f78..89e82d40d 100644 --- a/clients/dotnet/src/AgentHostProtocol.Abstractions/Generated/Commands.generated.cs +++ b/clients/dotnet/src/AgentHostProtocol.Abstractions/Generated/Commands.generated.cs @@ -1903,6 +1903,13 @@ public sealed record AuthenticateParams /// see {@link /specification/authentication#account-selection-hints | Account selection hints}. [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] public string? AccountId { get; init; } + + /// Optional human-readable label for the client's selected account. + /// Display-only metadata; labels need not be unique or stable. + /// Hosts MUST NOT use this label to identify accounts, detect account changes, + /// or authorize access. + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public string? AccountLabel { get; init; } } /// Result of the `authenticate` command. diff --git a/clients/go/ahptypes/commands.generated.go b/clients/go/ahptypes/commands.generated.go index d7ed89448..f6e81f2a9 100644 --- a/clients/go/ahptypes/commands.generated.go +++ b/clients/go/ahptypes/commands.generated.go @@ -1370,6 +1370,11 @@ type AuthenticateParams struct { // Hosts MUST treat `accountId` as an opaque string. // see {@link /specification/authentication#account-selection-hints | Account selection hints}. AccountId *string `json:"accountId,omitempty"` + // Optional human-readable label for the client's selected account. + // Display-only metadata; labels need not be unique or stable. + // Hosts MUST NOT use this label to identify accounts, detect account changes, + // or authorize access. + AccountLabel *string `json:"accountLabel,omitempty"` } // Result of the `authenticate` command. diff --git a/clients/kotlin/src/main/kotlin/com/microsoft/agenthostprotocol/generated/Commands.generated.kt b/clients/kotlin/src/main/kotlin/com/microsoft/agenthostprotocol/generated/Commands.generated.kt index 11d1ba653..c5d65b73f 100644 --- a/clients/kotlin/src/main/kotlin/com/microsoft/agenthostprotocol/generated/Commands.generated.kt +++ b/clients/kotlin/src/main/kotlin/com/microsoft/agenthostprotocol/generated/Commands.generated.kt @@ -1638,7 +1638,14 @@ data class AuthenticateParams( * Hosts MUST treat `accountId` as an opaque string. * see {@link /specification/authentication#account-selection-hints | Account selection hints}. */ - val accountId: String? = null + val accountId: String? = null, + /** + * Optional human-readable label for the client's selected account. + * Display-only metadata; labels need not be unique or stable. + * Hosts MUST NOT use this label to identify accounts, detect account changes, + * or authorize access. + */ + val accountLabel: String? = null ) @Serializable diff --git a/clients/rust/crates/ahp-types/src/commands.rs b/clients/rust/crates/ahp-types/src/commands.rs index aeb2a2116..79e88a40e 100644 --- a/clients/rust/crates/ahp-types/src/commands.rs +++ b/clients/rust/crates/ahp-types/src/commands.rs @@ -1762,6 +1762,12 @@ pub struct AuthenticateParams { /// see {@link /specification/authentication#account-selection-hints | Account selection hints}. #[serde(default, skip_serializing_if = "Option::is_none")] pub account_id: Option, + /// Optional human-readable label for the client's selected account. + /// Display-only metadata; labels need not be unique or stable. + /// Hosts MUST NOT use this label to identify accounts, detect account changes, + /// or authorize access. + #[serde(default, skip_serializing_if = "Option::is_none")] + pub account_label: Option, } /// Result of the `authenticate` command. diff --git a/clients/swift/AgentHostProtocol/Sources/AgentHostProtocol/Generated/Commands.generated.swift b/clients/swift/AgentHostProtocol/Sources/AgentHostProtocol/Generated/Commands.generated.swift index 2577e5cd4..26a8d362f 100644 --- a/clients/swift/AgentHostProtocol/Sources/AgentHostProtocol/Generated/Commands.generated.swift +++ b/clients/swift/AgentHostProtocol/Sources/AgentHostProtocol/Generated/Commands.generated.swift @@ -1956,6 +1956,11 @@ public struct AuthenticateParams: Codable, Sendable, Equatable { /// Hosts MUST treat `accountId` as an opaque string. /// see {@link /specification/authentication#account-selection-hints | Account selection hints}. public var accountId: String? + /// Optional human-readable label for the client's selected account. + /// Display-only metadata; labels need not be unique or stable. + /// Hosts MUST NOT use this label to identify accounts, detect account changes, + /// or authorize access. + public var accountLabel: String? enum CodingKeys: String, CodingKey { case channel @@ -1966,6 +1971,7 @@ public struct AuthenticateParams: Codable, Sendable, Equatable { case scopes case target case accountId + case accountLabel } public init( @@ -1976,7 +1982,8 @@ public struct AuthenticateParams: Codable, Sendable, Equatable { expiresIn: Int? = nil, scopes: [String]? = nil, target: AuthenticateTarget? = nil, - accountId: String? = nil + accountId: String? = nil, + accountLabel: String? = nil ) { self.channel = channel self.meta = meta @@ -1986,6 +1993,7 @@ public struct AuthenticateParams: Codable, Sendable, Equatable { self.scopes = scopes self.target = target self.accountId = accountId + self.accountLabel = accountLabel } } diff --git a/docs/.changes/20261113-authenticate-account-label.json b/docs/.changes/20261113-authenticate-account-label.json new file mode 100644 index 000000000..2c2e1ec90 --- /dev/null +++ b/docs/.changes/20261113-authenticate-account-label.json @@ -0,0 +1,4 @@ +{ + "type": "added", + "message": "Optional `AuthenticateParams.accountLabel` for display-only account labels alongside authentication tokens." +} diff --git a/docs/specification/authentication.md b/docs/specification/authentication.md index 4cb1cc928..d51b5b855 100644 --- a/docs/specification/authentication.md +++ b/docs/specification/authentication.md @@ -158,6 +158,8 @@ The `target.kind` discriminant is extensible so future consumers, such as [host- Clients MAY include `accountId` alongside the token to identify their selected account. Hosts can compare `accountId` values to detect when the underlying account has changed. When present, `accountId` MUST be a nonempty string, and hosts MUST treat it as opaque. +Clients MAY also include `accountLabel`, a human-readable label for the selected account. It is client-supplied, display-only metadata and need not be unique or stable. Hosts MUST NOT use it to identify accounts, detect account changes, or authorize access; token validation remains authoritative. + ```jsonc { "jsonrpc": "2.0", @@ -167,11 +169,16 @@ Clients MAY include `accountId` alongside the token to identify their selected a "channel": "ahp-root://", "resource": "https://api.example.com", "token": "access_token", - "accountId": "client-selection-7" + "accountId": "client-selection-7", + "accountLabel": "Example account" } } ``` +`accountLabel` is optional independently of `accountId`. Older hosts ignore it, and newer hosts continue accepting requests that omit it. No capability or protocol-version change is required. + +Wire compatibility does not imply native source or binary compatibility: Rust struct literals must add `account_label: None` when omitting the label, and existing Kotlin data-class binaries must be rebuilt against the updated generated model. + ## Error Handling ### `AuthRequired` Error Code diff --git a/schema/commands.schema.json b/schema/commands.schema.json index bf924f092..8b135f9a4 100644 --- a/schema/commands.schema.json +++ b/schema/commands.schema.json @@ -1055,6 +1055,10 @@ "type": "string", "description": "Optional identifier for the client's selected account, sent alongside the token.\nHosts can compare `accountId` values to detect when the underlying account has changed.\nHosts MUST treat `accountId` as an opaque string.\nsee {@link /specification/authentication#account-selection-hints | Account selection hints}.", "minLength": 1 + }, + "accountLabel": { + "type": "string", + "description": "Optional human-readable label for the client's selected account.\nDisplay-only metadata; labels need not be unique or stable.\nHosts MUST NOT use this label to identify accounts, detect account changes,\nor authorize access." } }, "required": [ diff --git a/schema/errors.schema.json b/schema/errors.schema.json index ef51716dd..bc3c72d58 100644 --- a/schema/errors.schema.json +++ b/schema/errors.schema.json @@ -7196,6 +7196,10 @@ "type": "string", "description": "Optional identifier for the client's selected account, sent alongside the token.\nHosts can compare `accountId` values to detect when the underlying account has changed.\nHosts MUST treat `accountId` as an opaque string.\nsee {@link /specification/authentication#account-selection-hints | Account selection hints}.", "minLength": 1 + }, + "accountLabel": { + "type": "string", + "description": "Optional human-readable label for the client's selected account.\nDisplay-only metadata; labels need not be unique or stable.\nHosts MUST NOT use this label to identify accounts, detect account changes,\nor authorize access." } }, "required": [ diff --git a/scripts/generate-json-schema.test.ts b/scripts/generate-json-schema.test.ts index 6cd94baa3..96c05e5e2 100644 --- a/scripts/generate-json-schema.test.ts +++ b/scripts/generate-json-schema.test.ts @@ -411,6 +411,27 @@ describe('generated JSON schemas', () => { ]); }); + it('accepts an optional account label with or without an account-selection hint', () => { + if (file !== 'commands.schema.json') { + return; + } + const defs = schema.$defs as Record>; + const authenticate = defs.AuthenticateParams; + const base = { channel: 'ahp-root://', resource: 'https://api.example.com', token: 'test-token' }; + for (const value of [ + base, + { ...base, accountId: 'selection-1', accountLabel: 'Example account' }, + { ...base, accountLabel: 'Example account' }, + { ...base, accountLabel: '' }, + ]) { + assert.equal(schemaAccepts(schema, authenticate as JsonNode, value), true, JSON.stringify(value)); + } + for (const accountLabel of [42, true, null, {}, []]) { + const value = { ...base, accountLabel }; + assert.equal(schemaAccepts(schema, authenticate as JsonNode, value), false, JSON.stringify(value)); + } + }); + it('accepts optional, empty, single-kind, and combined automation disable conditions', () => { const defs = schema.$defs as Record>; const afterRuns = { kind: 'afterRuns', max: 3 }; diff --git a/types/common/commands.ts b/types/common/commands.ts index d5c42df8f..df05fc688 100644 --- a/types/common/commands.ts +++ b/types/common/commands.ts @@ -1512,6 +1512,13 @@ export interface AuthenticateParams extends BaseParams { * @minLength 1 */ accountId?: string; + /** + * Optional human-readable label for the client's selected account. + * Display-only metadata; labels need not be unique or stable. + * Hosts MUST NOT use this label to identify accounts, detect account changes, + * or authorize access. + */ + accountLabel?: string; } /** diff --git a/types/test-cases/round-trips/094-authenticate-account-label.json b/types/test-cases/round-trips/094-authenticate-account-label.json new file mode 100644 index 000000000..e8199e661 --- /dev/null +++ b/types/test-cases/round-trips/094-authenticate-account-label.json @@ -0,0 +1,22 @@ +{ + "name": "authenticate-account-label", + "group": "A", + "description": "Authentication preserves an optional display label alongside the opaque account-selection hint.", + "type": "AuthenticateParams", + "input": { + "channel": "ahp-root://", + "resource": "https://api.example.com", + "token": "test-token", + "accountId": "client-selection-7", + "accountLabel": "Example account" + }, + "acceptableOutputs": [ + { + "channel": "ahp-root://", + "resource": "https://api.example.com", + "token": "test-token", + "accountId": "client-selection-7", + "accountLabel": "Example account" + } + ] +}