Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -1903,6 +1903,13 @@ public sealed record AuthenticateParams
/// see {@link /specification/authentication#account-selection-hints | Account selection hints}.</summary>
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
public string? AccountId { get; init; }

/// <summary>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.</summary>
[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
public string? AccountLabel { get; init; }
}

/// <summary>Result of the `authenticate` command.
Expand Down
5 changes: 5 additions & 0 deletions clients/go/ahptypes/commands.generated.go
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 6 additions & 0 deletions clients/rust/crates/ahp-types/src/commands.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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<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.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub account_label: Option<String>,
}

/// Result of the `authenticate` command.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -1966,6 +1971,7 @@ public struct AuthenticateParams: Codable, Sendable, Equatable {
case scopes
case target
case accountId
case accountLabel
}

public init(
Expand All @@ -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
Expand All @@ -1986,6 +1993,7 @@ public struct AuthenticateParams: Codable, Sendable, Equatable {
self.scopes = scopes
self.target = target
self.accountId = accountId
self.accountLabel = accountLabel
}
}

Expand Down
4 changes: 4 additions & 0 deletions docs/.changes/20261113-authenticate-account-label.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{
"type": "added",
"message": "Optional `AuthenticateParams.accountLabel` for display-only account labels alongside authentication tokens."
}
9 changes: 8 additions & 1 deletion docs/specification/authentication.md
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand All @@ -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
Expand Down
4 changes: 4 additions & 0 deletions schema/commands.schema.json
Original file line number Diff line number Diff line change
Expand Up @@ -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": [
Expand Down
4 changes: 4 additions & 0 deletions schema/errors.schema.json
Original file line number Diff line number Diff line change
Expand Up @@ -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": [
Expand Down
21 changes: 21 additions & 0 deletions scripts/generate-json-schema.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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<string, Record<string, unknown>>;
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<string, Record<string, unknown>>;
const afterRuns = { kind: 'afterRuns', max: 3 };
Expand Down
7 changes: 7 additions & 0 deletions types/common/commands.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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;
}

/**
Expand Down
Original file line number Diff line number Diff line change
@@ -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"
}
]
}
Loading