@peac/mappings-a2a 0.12.4 → 0.12.6

package/README.md

@@ -1,8 +1,6 @@
 # @peac/mappings-a2a
 
-Agent-to-Agent Protocol (A2A) integration for PEAC.
-
-Maps PEAC evidence carriers to A2A metadata (TaskStatus, Message, Artifact) per A2A spec v0.3.0.
+Agent-to-Agent Protocol (A2A) integration for PEAC: maps A2A agent cards, task states, and metadata to PEAC evidence carriers.
 
 ## Installation
 
@@ -10,9 +8,117 @@ Maps PEAC evidence carriers to A2A metadata (TaskStatus, Message, Artifact) per
 pnpm add @peac/mappings-a2a
 ```
 
-## Documentation
+## What It Does
+
+`@peac/mappings-a2a` bridges PEAC signed interaction receipts and the Agent-to-Agent Protocol (A2A). It normalizes A2A v0.3.0 and v1.0.0 structures into a consistent shape, attaches and extracts PEAC evidence carriers from A2A metadata, and discovers PEAC capabilities advertised by remote agents. All carrier operations enforce transport constraints (64 KB embed limit for A2A).
+
+## How Do I Use It?
+
+### Normalize an A2A Agent Card
+
+Accept either v0.3.0 or v1.0.0 Agent Cards and get a consistent interface:
+
+```typescript
+import { normalizeAgentCard } from '@peac/mappings-a2a';
+
+const card = {
+  name: 'billing-agent',
+  supportedInterfaces: [
+    { url: 'https://billing.example.com', protocolBinding: 'http+json', protocolVersion: '1.0.0' },
+  ],
+};
+const normalized = normalizeAgentCard(card);
+
+if (normalized) {
+  console.log(normalized.version); // '1.0.0'
+  console.log(normalized.url); // 'https://billing.example.com'
+}
+```
+
+### Normalize a task state across versions
+
+```typescript
+import { normalizeTaskState } from '@peac/mappings-a2a';
+
+// v0.3.0 value normalized to v1.0.0 canonical form
+console.log(normalizeTaskState('working')); // 'TASK_STATE_WORKING'
+
+// v1.0.0 values pass through unchanged
+console.log(normalizeTaskState('TASK_STATE_COMPLETED')); // 'TASK_STATE_COMPLETED'
+```
+
+### Attach a receipt to A2A TaskStatus metadata
+
+```typescript
+import { attachReceiptToTaskStatus } from '@peac/mappings-a2a';
+import type { PeacEvidenceCarrier } from '@peac/kernel';
+
+const carrier: PeacEvidenceCarrier = {
+  receipt_ref: 'sha256-abc123...',
+  receipt_jws: 'eyJ...',
+};
+
+const status = { state: 'TASK_STATE_COMPLETED', metadata: {} };
+attachReceiptToTaskStatus(status, [carrier]);
+// status.metadata now contains the PEAC extension payload
+```
+
+### Extract receipts from A2A metadata
+
+```typescript
+import { extractReceiptFromMetadata } from '@peac/mappings-a2a';
+
+const result = extractReceiptFromMetadata(taskStatus.metadata);
+if (result) {
+  console.log(result.receipts.length); // number of valid carriers
+  console.log(result.meta.transport); // 'a2a'
+}
+```
+
+### Use the carrier adapter
+
+```typescript
+import { A2ACarrierAdapter, createA2ACarrierMeta } from '@peac/mappings-a2a';
+
+const adapter = new A2ACarrierAdapter();
+const meta = createA2ACarrierMeta();
+
+// Extract from incoming TaskStatus
+const extracted = adapter.extract(incomingStatus);
+
+// Attach to outgoing TaskStatus
+const outgoing = adapter.attach(responseStatus, carriers, meta);
+```
+
+### Discover PEAC capabilities from a remote agent
+
+```typescript
+import { discoverPeacCapabilities } from '@peac/mappings-a2a';
+
+const result = await discoverPeacCapabilities('https://agent.example.com');
+if (result) {
+  console.log(result.source); // 'agent_card' | 'well_known' | 'header_probe'
+  console.log(result.kinds); // supported receipt kinds
+  console.log(result.carrier_formats); // supported carrier formats
+}
+```
+
+## Integrates With
+
+- `@peac/kernel` (Layer 0): Evidence carrier types and constants
+- `@peac/schema` (Layer 1): Carrier schema validation and receipt ref consistency
+- `@peac/protocol` (Layer 3): Receipt issuance and verification
+- `@peac/mcp-server` (Layer 5): MCP tool server with A2A interoperability
+
+## For Agent Developers
+
+If you are building an AI agent that communicates via A2A and needs signed interaction receipts:
 
-See [peacprotocol.org](https://www.peacprotocol.org) for full documentation.
+- Use `normalizeAgentCard()` and `normalizeTaskState()` to handle both A2A v0.3.0 and v1.0.0 inputs
+- Use `attachReceiptToTaskStatus()` to embed evidence in outgoing A2A messages
+- Use `extractReceiptFromMetadata()` to retrieve evidence from incoming A2A messages
+- Use `A2ACarrierAdapter` for a transport-agnostic carrier interface
+- Use `discoverPeacCapabilities()` to check whether a remote agent supports PEAC before sending receipts
 
 ## License
 

package/dist/auth/device-code.d.ts

@@ -0,0 +1,86 @@
+/**
+ * OAuth 2.0 Device Authorization Grant types for A2A.
+ *
+ * Types only: no implementation in this release. Device Code flow
+ * (RFC 8628) is an alternative auth model for headless A2A agents
+ * that cannot handle browser redirects.
+ *
+ * All type names and field names mirror RFC 8628 wire format exactly.
+ * Normalization (if needed) belongs in a separate layer.
+ */
+/**
+ * A2A Device Code flow configuration.
+ *
+ * Field names mirror the A2A spec OAuth flow object for Device Code.
+ */
+export interface A2ADeviceCodeFlowConfig {
+    /** Device authorization endpoint URL (HTTPS required) */
+    readonly deviceAuthorizationUrl: string;
+    /** Token endpoint URL (HTTPS required) */
+    readonly tokenUrl: string;
+    /** Refresh token endpoint URL (optional, HTTPS required) */
+    readonly refreshUrl?: string;
+    /** Requested scopes */
+    readonly scopes?: readonly string[];
+}
+/**
+ * Device authorization request parameters (RFC 8628 Section 3.1).
+ *
+ * Wire field names per the RFC.
+ */
+export interface DeviceCodeRequest {
+    /** Client identifier */
+    readonly client_id: string;
+    /** Space-delimited scopes (wire format) */
+    readonly scope?: string;
+}
+/**
+ * Device authorization response from the authorization server (RFC 8628 Section 3.2).
+ *
+ * All field names match the RFC 8628 JSON wire format.
+ */
+export interface DeviceCodeResponse {
+    /** Device verification code */
+    readonly device_code: string;
+    /** End-user verification code (short, displayed to user) */
+    readonly user_code: string;
+    /** End-user verification URI */
+    readonly verification_uri: string;
+    /** Optional complete verification URI with user_code pre-filled */
+    readonly verification_uri_complete?: string;
+    /** Lifetime of device_code and user_code in seconds */
+    readonly expires_in: number;
+    /** Minimum polling interval in seconds (default 5 per RFC 8628 Section 3.2) */
+    readonly interval?: number;
+}
+/**
+ * Token endpoint error codes during Device Code polling (RFC 8628 Section 3.5).
+ *
+ * These are the raw wire values returned in the `error` field of the
+ * token endpoint error response during device authorization polling.
+ */
+export type DeviceCodePollingError = 'authorization_pending' | 'slow_down' | 'access_denied' | 'expired_token';
+/**
+ * Token endpoint error response during Device Code polling.
+ *
+ * Wire shape per RFC 8628 Section 3.5 + OAuth 2.0 error response format.
+ */
+export interface DeviceCodeErrorResponse {
+    /** RFC 8628 polling error code */
+    readonly error: DeviceCodePollingError;
+    /** Human-readable error description */
+    readonly error_description?: string;
+}
+/**
+ * Successful token response from Device Code flow completion.
+ *
+ * Same shape as standard OAuth 2.0 token response (RFC 6749 Section 5.1).
+ */
+export interface DeviceCodeTokenResponse {
+    readonly access_token: string;
+    readonly token_type: string;
+    readonly expires_in?: number;
+    readonly refresh_token?: string;
+    readonly scope?: string;
+}
+//# sourceMappingURL=device-code.d.ts.map

package/dist/auth/device-code.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-code.d.ts","sourceRoot":"","sources":["../../src/auth/device-code.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,yDAAyD;IACzD,QAAQ,CAAC,sBAAsB,EAAE,MAAM,CAAC;IACxC,0CAA0C;IAC1C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,4DAA4D;IAC5D,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,uBAAuB;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAMD;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,wBAAwB;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,+BAA+B;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,4DAA4D;IAC5D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,gCAAgC;IAChC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,mEAAmE;IACnE,QAAQ,CAAC,yBAAyB,CAAC,EAAE,MAAM,CAAC;IAC5C,uDAAuD;IACvD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;GAKG;AACH,MAAM,MAAM,sBAAsB,GAC9B,uBAAuB,GACvB,WAAW,GACX,eAAe,GACf,eAAe,CAAC;AAEpB;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,kCAAkC;IAClC,QAAQ,CAAC,KAAK,EAAE,sBAAsB,CAAC;IACvC,uCAAuC;IACvC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACrC;AAED;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB"}

package/dist/auth/errors.d.ts

@@ -0,0 +1,108 @@
+/**
+ * A2A auth error mapping to google.rpc.Status with ErrorInfo.
+ *
+ * A2A v1.0 uses gRPC-style status codes for transport errors. For
+ * A2A-specific errors, implementations include `google.rpc.ErrorInfo`
+ * in `status.details[]`. This module produces the full Status + ErrorInfo
+ * shape for auth-related A2A errors.
+ */
+/**
+ * gRPC canonical status codes used in A2A auth error responses.
+ * Values match google.rpc.Code numeric assignments.
+ */
+export declare const GrpcStatusCode: {
+    readonly OK: 0;
+    readonly INVALID_ARGUMENT: 3;
+    readonly NOT_FOUND: 5;
+    readonly PERMISSION_DENIED: 7;
+    readonly INTERNAL: 13;
+    readonly UNAVAILABLE: 14;
+    readonly UNAUTHENTICATED: 16;
+};
+export type GrpcStatusCodeValue = (typeof GrpcStatusCode)[keyof typeof GrpcStatusCode];
+/**
+ * google.rpc.ErrorInfo per https://cloud.google.com/apis/design/errors.
+ *
+ * Included in `status.details[]` for A2A-specific auth errors.
+ */
+export interface GrpcErrorInfo {
+    /** Fully-qualified type URL for ErrorInfo */
+    readonly '@type': 'type.googleapis.com/google.rpc.ErrorInfo';
+    /** Machine-readable error reason (SCREAMING_SNAKE_CASE) */
+    readonly reason: string;
+    /** Domain for the error (always 'a2a-protocol.org' per A2A spec) */
+    readonly domain: string;
+    /** Key-value metadata providing additional error context */
+    readonly metadata: Readonly<Record<string, string>>;
+}
+/**
+ * google.rpc.Status with typed ErrorInfo detail.
+ *
+ * This is the wire shape returned in A2A gRPC error responses and
+ * JSON-RPC error data objects.
+ */
+export interface GrpcStatus {
+    /** gRPC canonical status code */
+    readonly code: GrpcStatusCodeValue;
+    /** Human-readable error message */
+    readonly message: string;
+    /** Structured error details (contains ErrorInfo for A2A-specific errors) */
+    readonly details: readonly GrpcErrorInfo[];
+}
+declare const AUTH_ERROR_DEFS: {
+    readonly PKCE_MISMATCH: {
+        readonly grpcCode: 16;
+        readonly message: "PKCE code challenge verification failed";
+        readonly reason: "PKCE_CHALLENGE_MISMATCH";
+    };
+    readonly PKCE_INVALID_VERIFIER: {
+        readonly grpcCode: 3;
+        readonly message: "PKCE code verifier does not meet RFC 7636 requirements";
+        readonly reason: "PKCE_INVALID_VERIFIER";
+    };
+    readonly TOKEN_EXCHANGE_FAILED: {
+        readonly grpcCode: 16;
+        readonly message: "OAuth token exchange failed";
+        readonly reason: "TOKEN_EXCHANGE_FAILED";
+    };
+    readonly AUTH_SERVER_UNAVAILABLE: {
+        readonly grpcCode: 14;
+        readonly message: "Authorization server is unavailable";
+        readonly reason: "AUTH_SERVER_UNAVAILABLE";
+    };
+    readonly INVALID_AUTH_CODE: {
+        readonly grpcCode: 16;
+        readonly message: "Authorization code is invalid or expired";
+        readonly reason: "INVALID_AUTH_CODE";
+    };
+    readonly INVALID_CLIENT: {
+        readonly grpcCode: 7;
+        readonly message: "Client authentication failed";
+        readonly reason: "INVALID_CLIENT";
+    };
+    readonly SCOPE_DENIED: {
+        readonly grpcCode: 7;
+        readonly message: "Requested scope was denied by the authorization server";
+        readonly reason: "SCOPE_DENIED";
+    };
+    readonly DEVICE_CODE_EXPIRED: {
+        readonly grpcCode: 16;
+        readonly message: "Device authorization code has expired";
+        readonly reason: "DEVICE_CODE_EXPIRED";
+    };
+};
+export type A2AAuthErrorCode = keyof typeof AUTH_ERROR_DEFS;
+/**
+ * Create a google.rpc.Status with ErrorInfo for an A2A auth error.
+ *
+ * Returns the full Status shape with `details[]` containing a single
+ * `google.rpc.ErrorInfo` entry, as required by the A2A spec for
+ * implementation-specific errors.
+ *
+ * @param errorCode - A2A auth error code
+ * @param metadata - Additional key-value context for ErrorInfo.metadata
+ * @returns google.rpc.Status with embedded ErrorInfo
+ */
+export declare function createA2AAuthStatus(errorCode: A2AAuthErrorCode, metadata?: Record<string, string>): GrpcStatus;
+export {};
+//# sourceMappingURL=errors.d.ts.map

package/dist/auth/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/auth/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH;;;GAGG;AACH,eAAO,MAAM,cAAc;;;;;;;;CAQjB,CAAC;AAEX,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,OAAO,cAAc,CAAC,CAAC;AAMvF;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,6CAA6C;IAC7C,QAAQ,CAAC,OAAO,EAAE,0CAA0C,CAAC;IAC7D,2DAA2D;IAC3D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,oEAAoE;IACpE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,4DAA4D;IAC5D,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACrD;AAMD;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,iCAAiC;IACjC,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,mCAAmC;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,CAAC;CAC5C;AAeD,QAAA,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyC4B,CAAC;AAElD,MAAM,MAAM,gBAAgB,GAAG,MAAM,OAAO,eAAe,CAAC;AAM5D;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,gBAAgB,EAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAChC,UAAU,CAcZ"}

package/dist/auth/evidence.d.ts

@@ -0,0 +1,68 @@
+/**
+ * A2A auth event to PEAC evidence mapping.
+ *
+ * Maps A2A OAuth authentication events to access extension observations.
+ * Auth success produces an **observation** receipt, never an automatic
+ * access-decision receipt. The caller must explicitly construct
+ * access-decision receipts when a business-level decision is made.
+ */
+import type { JsonObject } from '@peac/kernel';
+import { ACCESS_EXTENSION_KEY } from '@peac/schema';
+/** Supported A2A auth methods */
+export type A2AAuthMethod = 'oauth2_pkce' | 'oauth2_device_code' | 'oauth2_client_credentials';
+/**
+ * Input event describing an A2A authentication occurrence.
+ *
+ * This represents what happened at the auth layer, not a business
+ * decision about whether to grant access.
+ */
+export interface A2AAuthEvent {
+    /** Auth method used */
+    readonly method: A2AAuthMethod;
+    /** Resource URI that was authenticated against */
+    readonly resource: string;
+    /** Action that was requested (e.g., 'authenticate', 'tasks/send') */
+    readonly action: string;
+    /** OAuth scopes that were granted (from token response) */
+    readonly grantedScopes?: readonly string[];
+    /** Authorization server that issued the token */
+    readonly authServer?: string;
+    /** Client identifier used */
+    readonly clientId?: string;
+    /** ISO 8601 timestamp of the auth event */
+    readonly timestamp?: string;
+}
+/**
+ * Output structure for the access extension in a Wire 0.2 receipt.
+ *
+ * Uses `org.peacprotocol/access` extension group with `auth_event`
+ * set to `'observation'` to distinguish from access-decision receipts.
+ */
+export interface A2AAuthEvidenceResult {
+    /** Extension key for receipt `ext` field */
+    readonly extensionKey: typeof ACCESS_EXTENSION_KEY;
+    /** Access extension fields for the receipt */
+    readonly extension: {
+        readonly resource: string;
+        readonly action: string;
+        readonly decision: 'review';
+    };
+    /** Additional evidence metadata for the receipt `evidence` field */
+    readonly evidence: JsonObject;
+}
+/**
+ * Map an A2A auth event to access extension evidence.
+ *
+ * Produces an **observation** receipt: `decision` is always `'review'`,
+ * indicating that authentication occurred but no access decision was
+ * made by the evidence layer. Callers who need `'allow'` or `'deny'`
+ * decisions must explicitly construct those receipts.
+ *
+ * Tokens are never included in the evidence. Only structural metadata
+ * (method, scopes, server, client_id) is recorded.
+ *
+ * @param event - A2A auth event to map
+ * @returns Extension data and evidence metadata for receipt construction
+ */
+export declare function fromA2AAuthEvent(event: A2AAuthEvent): A2AAuthEvidenceResult;
+//# sourceMappingURL=evidence.d.ts.map

package/dist/auth/evidence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidence.d.ts","sourceRoot":"","sources":["../../src/auth/evidence.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAMpD,iCAAiC;AACjC,MAAM,MAAM,aAAa,GAAG,aAAa,GAAG,oBAAoB,GAAG,2BAA2B,CAAC;AAE/F;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,uBAAuB;IACvB,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,kDAAkD;IAClD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,qEAAqE;IACrE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,2DAA2D;IAC3D,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,iDAAiD;IACjD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,6BAA6B;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,2CAA2C;IAC3C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,4CAA4C;IAC5C,QAAQ,CAAC,YAAY,EAAE,OAAO,oBAAoB,CAAC;IACnD,8CAA8C;IAC9C,QAAQ,CAAC,SAAS,EAAE;QAClB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;KAC7B,CAAC;IACF,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;CAC/B;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,YAAY,GAAG,qBAAqB,CAmC3E"}

package/dist/auth/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * A2A v1.0 authentication surface.
+ *
+ * OAuth 2.0 PKCE (S256), Device Code types, auth evidence mapping,
+ * and google.rpc.Status error modeling.
+ */
+export { generatePKCEChallenge, computeS256Challenge, validatePKCEVerifier } from './pkce.js';
+export type { PKCEChallenge } from './pkce.js';
+export { buildAuthorizationRequest, exchangeAuthorizationCode } from './oauth.js';
+export type { A2AOAuthConfig, AuthorizationRequest, TokenResponse, FetchFn } from './oauth.js';
+export type { A2ADeviceCodeFlowConfig, DeviceCodeRequest, DeviceCodeResponse, DeviceCodePollingError, DeviceCodeErrorResponse, DeviceCodeTokenResponse, } from './device-code.js';
+export { fromA2AAuthEvent } from './evidence.js';
+export type { A2AAuthMethod, A2AAuthEvent, A2AAuthEvidenceResult } from './evidence.js';
+export { GrpcStatusCode, createA2AAuthStatus } from './errors.js';
+export type { GrpcStatusCodeValue, GrpcErrorInfo, GrpcStatus, A2AAuthErrorCode } from './errors.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/auth/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AAC9F,YAAY,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAG/C,OAAO,EAAE,yBAAyB,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AAClF,YAAY,EAAE,cAAc,EAAE,oBAAoB,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAG/F,YAAY,EACV,uBAAuB,EACvB,iBAAiB,EACjB,kBAAkB,EAClB,sBAAsB,EACtB,uBAAuB,EACvB,uBAAuB,GACxB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACjD,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAGxF,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClE,YAAY,EAAE,mBAAmB,EAAE,aAAa,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC"}

package/dist/auth/oauth.d.ts

@@ -0,0 +1,100 @@
+/**
+ * OAuth 2.0 authorization code flow utilities for A2A v1.0.
+ *
+ * A2A v1.0 specifies OAuth 2.0 with PKCE as the preferred auth model.
+ * All network calls accept a `fetchFn` parameter (no global fetch).
+ *
+ * Config field names mirror the A2A spec OAuth flow object:
+ * authorizationUrl, tokenUrl, refreshUrl, scopes, pkceRequired.
+ */
+/**
+ * Minimal fetch signature for OAuth network calls.
+ *
+ * Narrower than global `fetch` to avoid coupling to runtime-specific
+ * fetch extensions (AbortSignal, Request objects, etc.).
+ */
+export type FetchFn = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    json: () => Promise<unknown>;
+    text: () => Promise<string>;
+}>;
+/**
+ * OAuth 2.0 configuration for an A2A authorization server.
+ *
+ * Field names mirror the A2A spec OAuth flow object.
+ */
+export interface A2AOAuthConfig {
+    /** Authorization endpoint URL (HTTPS required) */
+    readonly authorizationUrl: string;
+    /** Token endpoint URL (HTTPS required) */
+    readonly tokenUrl: string;
+    /** Refresh token endpoint URL (optional, HTTPS required) */
+    readonly refreshUrl?: string;
+    /** Client identifier */
+    readonly clientId: string;
+    /** Redirect URI for authorization code delivery (HTTPS required) */
+    readonly redirectUri: string;
+    /** Requested scopes */
+    readonly scopes?: readonly string[];
+    /** Whether PKCE is required (always true for A2A v1.0) */
+    readonly pkceRequired?: boolean;
+    /** Additional authorization parameters (must not override reserved params) */
+    readonly extraParams?: Readonly<Record<string, string>>;
+}
+/**
+ * Authorization request parameters for constructing the redirect URL.
+ */
+export interface AuthorizationRequest {
+    /** Full authorization URL with query parameters */
+    readonly url: string;
+    /** PKCE code verifier (store securely; needed for token exchange) */
+    readonly codeVerifier: string;
+    /** State parameter for CSRF protection */
+    readonly state: string;
+}
+/**
+ * OAuth 2.0 token response from the authorization server.
+ */
+export interface TokenResponse {
+    readonly access_token: string;
+    readonly token_type: string;
+    readonly expires_in?: number;
+    readonly refresh_token?: string;
+    readonly scope?: string;
+}
+/**
+ * Build an authorization URL with PKCE challenge and state parameter.
+ *
+ * The caller must redirect the user-agent to the returned URL. The
+ * `codeVerifier` must be stored securely for the subsequent token
+ * exchange call.
+ *
+ * @param config - A2A OAuth server configuration
+ * @param pkce - PKCE challenge pair (from `generatePKCEChallenge()`)
+ * @returns Authorization request with URL, verifier, and state
+ * @throws Error if endpoint URLs are not HTTPS or extraParams override reserved params
+ */
+export declare function buildAuthorizationRequest(config: A2AOAuthConfig, pkce: {
+    readonly challenge: string;
+    readonly verifier: string;
+}): AuthorizationRequest;
+/**
+ * Exchange an authorization code for tokens.
+ *
+ * Sends a POST to the token endpoint with the authorization code and
+ * PKCE code verifier. Validates the verifier format before sending.
+ *
+ * @param code - Authorization code from the redirect callback
+ * @param verifier - PKCE code verifier from the authorization request
+ * @param config - A2A OAuth server configuration
+ * @param fetchFn - Fetch implementation (no global fetch)
+ * @returns Token response from the authorization server
+ * @throws Error if the token endpoint returns an error response
+ */
+export declare function exchangeAuthorizationCode(code: string, verifier: string, config: A2AOAuthConfig, fetchFn: FetchFn): Promise<TokenResponse>;
+//# sourceMappingURL=oauth.d.ts.map

package/dist/auth/oauth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth.d.ts","sourceRoot":"","sources":["../../src/auth/oauth.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAQH;;;;;GAKG;AACH,MAAM,MAAM,OAAO,GAAG,CACpB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;IACJ,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;CACd,KACE,OAAO,CAAC;IACX,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7B,IAAI,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;CAC7B,CAAC,CAAC;AAMH;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,kDAAkD;IAClD,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,0CAA0C;IAC1C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,4DAA4D;IAC5D,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,wBAAwB;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,oEAAoE;IACpE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,uBAAuB;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,0DAA0D;IAC1D,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAChC,8EAA8E;IAC9E,QAAQ,CAAC,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACzD;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,mDAAmD;IACnD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,qEAAqE;IACrE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,0CAA0C;IAC1C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAuBD;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE;IAAE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAC9D,oBAAoB,CAgCtB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,yBAAyB,CAC7C,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,aAAa,CAAC,CAyCxB"}

package/dist/auth/pkce.d.ts

@@ -0,0 +1,47 @@
+/**
+ * PKCE (Proof Key for Code Exchange) utilities for A2A OAuth flows.
+ *
+ * Implements S256 challenge method per RFC 7636. Plain method is
+ * rejected: S256 is the only method permitted by A2A v1.0.
+ */
+/**
+ * Result of PKCE challenge generation.
+ */
+export interface PKCEChallenge {
+    /** High-entropy code verifier (43-128 unreserved chars) */
+    readonly verifier: string;
+    /** Base64url-encoded SHA-256 hash of the verifier */
+    readonly challenge: string;
+    /** Always 'S256' */
+    readonly method: 'S256';
+}
+/**
+ * Generate a PKCE code verifier and S256 challenge.
+ *
+ * Uses `crypto.getRandomValues()` for verifier entropy (32 bytes,
+ * base64url-encoded to 43 chars). S256 only; plain method is not
+ * supported per A2A v1.0 security requirements.
+ *
+ * @returns PKCE verifier + challenge pair
+ */
+export declare function generatePKCEChallenge(): Promise<PKCEChallenge>;
+/**
+ * Compute the S256 challenge for a given verifier.
+ *
+ * `BASE64URL(SHA256(ASCII(code_verifier)))` per RFC 7636 Section 4.2.
+ *
+ * @param verifier - Code verifier string
+ * @returns Base64url-encoded SHA-256 digest
+ * @throws Error if verifier does not meet RFC 7636 requirements
+ */
+export declare function computeS256Challenge(verifier: string): Promise<string>;
+/**
+ * Validate that a PKCE code verifier meets RFC 7636 requirements.
+ *
+ * Checks length (43-128) and character set (unreserved per RFC 7636 Section 4.1).
+ *
+ * @param verifier - Code verifier to validate
+ * @throws Error with code `E_PKCE_INVALID_VERIFIER` if invalid
+ */
+export declare function validatePKCEVerifier(verifier: string): void;
+//# sourceMappingURL=pkce.d.ts.map

package/dist/auth/pkce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pkce.d.ts","sourceRoot":"","sources":["../../src/auth/pkce.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAmBH;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,2DAA2D;IAC3D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,qDAAqD;IACrD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,oBAAoB;IACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;GAQG;AACH,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,aAAa,CAAC,CAMpE;AAED;;;;;;;;GAQG;AACH,wBAAsB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAM5E;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAE3D"}