You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit af92bae
Browse filesBrowse the repository at this point in the historyBrowse files
feat: authorize task listings with JPA ownership scopes
Add optional backend-neutral authorization capabilities and an explicitly
selected JPA ownership provider. Apply matching authorization scopes to
count and page queries while preserving deny-by-default behavior and
bounded fallback checks with opaque-token recovery.
Persist exact UTF-8 subject identities as binary ownership keys and isolate
first-writer-wins insertion and confirmation transactions. Cover identity
equality and repeatable-read ownership races on PostgreSQL and MySQL, and
document schema migrations, provider selection, and cloud deployment.
Signed-off-by: Kabir Khan <kkhan@redhat.com>
The optional JPA module provides `JpaTaskAuthorizationProvider`. Adding the module does not select it. Explicitly enable the CDI alternative (in Quarkus, `quarkus.arc.selected-alternatives=org.a2aproject.sdk.extras.taskstore.database.jpa.JpaTaskAuthorizationProvider`), register `JpaTaskOwner` with `JpaTask` in the same `a2a-java` unit, and migrate the ownership table and complete index. See [Storage & Persistence](extra/storage.md) for PostgreSQL `BYTEA` and MySQL `VARBINARY(1024)` setup.
91
+
92
+
The provider requires authenticated subjects, denies unknown ownership, and records a persistent first owner without transfer. Strict UTF-8 subject identities have a 1,024-byte limit; malformed surrogates and oversized values are rejected. Case, accents, Unicode-normalization forms and trailing spaces remain distinct. There is no normalization, trimming, truncation or lossy hashing. Usernames must be unique across the deployment; multiple issuers or tenant-local names require namespaced keys or a custom policy. Backfill only from a trusted source preserving original identities.
93
+
94
+
Outside CDI, use `JpaTaskOwnershipRepository.create(entityManagerFactory, transactionManager)`, then `new JpaTaskAuthorizationProvider(repository)`, and pass it to the handler builder. The JTA factory and manager must govern the task database. Insertion and duplicate confirmation each run in a separate new transaction with a fresh persistence context; insertion rolls back before confirmation. Never instantiate the transaction helper directly, as this bypasses CDI interception.
95
+
96
+
## Optional backend capabilities
97
+
98
+
Core authorization stays independent of storage technology:
Existing providers inherit empty discovery. Stores define backend-specific capability interfaces and request them from the **same configured provider** used by the handler. Empty means bounded fallback; present means supported policy, including explicit all/none scopes. Exceptions fail the request and never mean unsupported or allow-all.
107
+
108
+
JPA requests `JpaTaskAuthorizationCapability.readScope(context, operation)`. Its closed scopes are `JpaTaskReadScope.OwnedBy(subject)`, `All`, and `None`. A capability represents the provider's **complete per-task policy for that operation**. Wrappers adding restrictions must not forward a broader delegate capability. Custom allow-all providers may expose `All` only when individual checks agree; it includes unowned tasks.
109
+
110
+
Both database `COUNT` and paginated `SELECT` apply the same scope and ordinary filters. The cursor never narrows the exact authorized total. Only returned page data is deserialized and transformed. The handler still applies its unconditional list gate and final task checks; these cannot repair an overbroad count or replace exact query equality.
111
+
112
+
Unsupported providers retain iterative checks. JPA exact counts can fail at the configured candidate ceiling, without returning partial totals. See [Configuration](configuration.md) for JPA fallback settings. Capability queries do not use these Java scan limits.
83
113
84
114
## Default authorized listing fallback
85
115
86
116
Stores that do not override `TaskStore.listAuthorized` use a bounded fallback over `list`. Each call scans all matching candidates to count authorized tasks, then separately traverses the requested page and looks ahead for more authorized tasks. This can scan the full candidate set twice, even for a small requested page.
87
117
88
-
The count scan fetches batches of 100 candidates. Counting and page traversal/lookahead each have separate limits of 300 queries or 20,000 returned candidate tasks, including denied tasks. Exceeding either limit throws `TaskStoreException` rather than returning a partial total; JPA configuration properties do not change these generic limits. Stores with larger candidate sets or more efficient query support should override `listAuthorized`, applying the supplied provider's authorization before pagination and counting authorized matches across all pages independently of the cursor.
118
+
The fallback fetches batches of up to 100 candidates and separately limits count queries (300), normal page/lookahead queries (300), and distinct candidate tasks per phase (20,000, including denied tasks). Up to 100 extra queries may recover an opaque continuation token within the final fetched batch. Exceeding any limit throws `TaskStoreException` rather than returning a partial total; JPA configuration properties do not change these generic limits. Stores with larger candidate sets or more efficient query support should override `listAuthorized`, applying the supplied provider's authorization before pagination and counting authorized matches across all pages independently of the cursor.
119
+
120
+
The exact `totalSize` assumes stable task data and authorization decisions. The default fallback does not share a snapshot between counting and page selection, so concurrent task additions, deletions, or updates can make the count, returned page, and continuation token disagree. Overrides follow their store's consistency and isolation guarantees; JPA count and page queries use the configured database isolation without an implied stronger snapshot guarantee.
89
121
90
-
The exact `totalSize` assumes stable task data and authorization decisions. The default fallback does not share a snapshot between counting and page selection, so concurrent task additions, deletions, or updates can make the count, returned page, and continuation token disagree. Overrides follow their store's consistency and isolation guarantees.
122
+
Without a provider, access is denied unless explicitly disabled. `a2a.authorization.required=false` only opts out when no provider is present; configured providers remain authoritative.
Copy file name to clipboardExpand all lines: docs/content/dev/configuration.md
+5-3Lines changed: 5 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -74,21 +74,23 @@ When enabled, task IDs referenced in incoming messages are looked up in the `Tas
74
74
a2a.authorization.required=true
75
75
```
76
76
77
+
A configured provider remains authoritative even when `a2a.authorization.required=false`; that flag only permits providerless access.
78
+
77
79
See [Task Authorization](authorization.md) for details on implementing a `TaskAuthorizationProvider`.
78
80
79
81
### JPA Task Store Authorized Listings
80
82
81
83
These settings apply when using the JPA Task Store together with a `TaskAuthorizationProvider`:
82
84
83
85
```properties
84
-
#Maximum candidate rows inspected while counting an authorized task listing (default: 10000)
86
+
#Fallback only: maximum candidates inspected for an exact authorized count (default: 10000)
85
87
a2a.max-scanned-tasks=10000
86
88
87
-
#Candidate rows fetched in each database query during that scan (default: 100)
89
+
#Fallback only: candidates fetched per query (default: 100)
88
90
a2a.authorization-scan-batch-size=100
89
91
```
90
92
91
-
`a2a.max-scanned-tasks` bounds the work performed while counting authorized tasks. The count must be exact, so a listing fails if the scan limit is reached before all matching candidates have been inspected. `a2a.authorization-scan-batch-size` controls the database fetch size within that budget. Both values must be greater than zero. Increase the batch size to reduce round trips when many candidates are denied; lower it to reduce memory used per query.
93
+
`a2a.max-scanned-tasks` bounds the work performed while counting authorized tasks. The count must be exact, so a listing fails if the scan limit is reached before all matching candidates have been inspected. `a2a.authorization-scan-batch-size` controls the database fetch size within that budget. Both values must be greater than zero when fallback is used. These settings apply only to providers without `JpaTaskAuthorizationCapability`; the explicitly selected `JpaTaskAuthorizationProvider` enables database-side count/page filtering without Java candidate-scan ceilings. Increase the batch size to reduce round trips when many candidates are denied; lower it to reduce memory used per query.
@@ -64,7 +68,7 @@ Create or update your `persistence.xml`:
64
68
65
69
### 3. Database Schema
66
70
67
-
The module automatically creates the required table:
71
+
Schema creation is controlled by the application. Production upgrades require an application-managed migration for both task and ownership tables before using the updated store. Register both entities in the same `a2a-java` unit; package scanning discovers them in Quarkus. The task schema includes:
68
72
69
73
```sql
70
74
CREATETABLEa2a_tasks (
@@ -77,6 +81,61 @@ CREATE TABLE a2a_tasks (
77
81
);
78
82
```
79
83
84
+
### 4. Ownership schema and authorization selection
Verify the actual binary type and complete index. PostgreSQL must use `BYTEA`, not a large-object OID. MySQL requires variable-length `VARBINARY(1024)`, not padded `BINARY`, text with a binary collation, or a prefix index. Other databases need an equivalent exact variable-length binary mapping.
107
+
108
+
The SDK uses strict UTF-8 and rejects malformed surrogates or subjects exceeding 1,024 encoded bytes before ownership access. Case, accents, Unicode-normalization and trailing-space distinctions remain significant; there is no normalization, trimming, truncation, padding or lossy hashing. Backfill only from a trusted source preserving original subject keys. Audit legacy text-collation associations and lossless conversion; a migration cannot recover distinctions already discarded.
109
+
110
+
Adding the module selects the task store but does not enable an authorization provider. Explicitly select the supplied owner-only provider in Quarkus:
Use the Jakarta CDI annotations and the JPA module's provider/repository types. Choose the producer or Quarkus alternative selection, avoiding ambiguous providers. The repository uses an intercepted JTA helper: insertion and duplicate confirmation each run in a separate `REQUIRES_NEW` transaction with a fresh persistence context. Confirmation starts after insertion rollback, so a stale repeatable-read caller cannot hide committed ownership or become rollback-only. Outside CDI, use `JpaTaskOwnershipRepository.create(entityManagerFactory, transactionManager)` and pass `new JpaTaskAuthorizationProvider(repository)` to `DefaultRequestHandler.builder().authorizationProvider(provider)`. The factory must be JTA-enabled for the same database/transaction manager. Do not directly instantiate the transaction helper.
130
+
131
+
Authenticate `ServerCallContext.getUser()` and supply a username unique across your identity domain. Multiple issuers or tenant-local names require stable namespaced keys or a custom policy. Anonymous users and unknown ownership are denied; recording is first-writer-wins across replicas. An owner row may precede its task, so there is no immediate task foreign key. A persisted task remains inaccessible until ownership is recorded. Store deletion removes ownership in the same transaction; direct database maintenance must clean up both tables. Replicas must share ownership storage.
132
+
133
+
With no provider, authorization is required by default. Only deliberate providerless deployments should set `a2a.authorization.required=false`. Configured providers remain authoritative with that setting. An explicitly configured allow-all provider may expose `JpaTaskReadScope.All`, including unowned tasks, if its individual checks agree.
134
+
135
+
A supported `JpaTaskAuthorizationCapability` restricts both database count and page queries. The exact authorized total excludes the cursor and is repeated on every page; the page query alone uses the cursor. The handler's list gate and final checks remain. Counts and pages follow configured database isolation, without an implied stronger snapshot guarantee.
136
+
137
+
Unsupported providers retain iterative checks in Java. Their exact count may fail at `a2a.max-scanned-tasks`; `a2a.authorization-scan-batch-size` controls fetch size. These limits do not apply to capability-based queries. Lookup or capability exceptions fail the request rather than switching policy. See [Task Authorization](../authorization.md) for capability contracts and [Configuration](../configuration.md) for fallback limits.
138
+
80
139
### Persistence Unit Name
81
140
82
141
The module uses the persistence unit name `"a2a-java"`. Ensure your `persistence.xml` defines a persistence unit with this name.
@@ -116,7 +175,7 @@ Create or update your `persistence.xml`:
This discovers `JpaTask`, `JpaTaskOwner` and `JpaPushNotificationConfig`. Schema generation remains an application choice; production upgrades require migrations.
0 commit comments