From 01a32c15daf114a7014876306b1acab0891daca6 Mon Sep 17 00:00:00 2001 From: Jeremi Joslin Date: Sat, 31 Oct 2026 21:01:53 +0700 Subject: [PATCH] fix: preserve exact Proposal inputs and bounded workflow metadata Signed-off-by: Jeremi Joslin --- crates/registry-breg-client-node/README.md | 17 +++ .../__test__/facade.test-d.ts | 8 ++ .../__test__/proposal-exact-json.test.js | 83 +++++++++++ crates/registry-breg-client-node/client.d.ts | 4 + crates/registry-breg-client-node/client.js | 4 +- crates/registry-breg-client-node/index.d.ts | 4 + crates/registry-breg-client-node/src/lib.rs | 23 +++ crates/registry-breg-client/README.md | 5 + crates/registry-breg-client/src/client.rs | 14 ++ crates/registry-breg-client/src/metadata.rs | 5 +- .../src/metadata_vocabulary_tests.rs | 51 +++++++ .../action_recovery_registry_revision.rs | 74 ++++++++++ .../tests/http_boundary.rs | 25 ++++ crates/registry-coordinator/src/adapters.rs | 12 ++ .../registry-coordinator/src/breg_action.rs | 8 +- .../registry-coordinator/src/breg_proposal.rs | 3 +- .../tests/breg_action_adapter.rs | 136 ++++++++++++++++++ .../tests/breg_proposal_adapter.rs | 33 ++++- .../tests/read_in_force_adapter.rs | 13 ++ .../breg/client.d.ts | 4 + .../registry-stack-client-node/breg/client.js | 4 +- .../breg/index.d.ts | 4 + products/coordinator/PRODUCT-CONTRACT.md | 9 ++ products/coordinator/SECURITY-REVIEW-NOTES.md | 31 ++++ 24 files changed, 565 insertions(+), 9 deletions(-) create mode 100644 crates/registry-breg-client-node/__test__/proposal-exact-json.test.js diff --git a/crates/registry-breg-client-node/README.md b/crates/registry-breg-client-node/README.md index e3e8a249cc..23dde3dda7 100644 --- a/crates/registry-breg-client-node/README.md +++ b/crates/registry-breg-client-node/README.md @@ -296,3 +296,20 @@ cache; `await provider.bearerToken()` uses that separate client-credentials cache. Neither method logs or persists the returned credential. The application must protect it and pass it explicitly to a resource client. The resource server still validates the signed authority and bounds. + +## Exact JSON Proposal transitions and listing + +Use `prepareProposalJson(proposal, operation, bodyJson, key)` when an edit +contains integers outside JavaScript's safe integer range, including nested +values that satisfy BReg's binary64 mutation model. Exact reads retain all +signed and unsigned 64-bit integers, while mutation preparation still refuses +integers that model cannot represent exactly. Decimal text such as `"0.7500"` stays a string with its lexical form. +The exact JSON decoder refuses duplicate members and lossy numeric literals. +The structured `prepareProposal` method continues to refuse unsafe numbers. + +`listProposalsJson(collection, queryJson)` accepts the same query contract as +`listProposals`, with explicit pagination and a metadata-selected collection. +Both methods delegate to the canonical Rust client. They retain the same +pre-I/O checks, lifecycle conditions, source binding, and caller-chosen key. +Persist and recover the returned `BRegPreparedProposal` through +`recoverProposal` before executing after a restart, just as for an object body. diff --git a/crates/registry-breg-client-node/__test__/facade.test-d.ts b/crates/registry-breg-client-node/__test__/facade.test-d.ts index 4fa134a4af..1b363b1d99 100644 --- a/crates/registry-breg-client-node/__test__/facade.test-d.ts +++ b/crates/registry-breg-client-node/__test__/facade.test-d.ts @@ -14,6 +14,7 @@ import { BRegRecoveredCreate, BRegProposal, BRegProposalGetBinding, + BRegProposalCollection, BRegPreparedProposal, BRegTombstoneBinding, AsOfListContinuation, @@ -59,6 +60,13 @@ declare const preparedAction: BRegPreparedAction declare const preparedCreate: BRegPreparedCreate declare const proposal: BRegProposal declare const proposalGet: BRegProposalGetBinding +declare const proposalCollection: BRegProposalCollection +client.listProposalsJson(proposalCollection, '{"limit":1}') +client.prepareProposalJson(proposal, 'edit', '{"input":{"wide":9223372036854775807}}', 'exact-key') +// @ts-expect-error Exact Proposal methods require JSON text. +client.prepareProposalJson(proposal, 'edit', {input: {}}, 'exact-key') +// @ts-expect-error Exact Proposal listing requires JSON text. +client.listProposalsJson(proposalCollection, {}) declare const preparedProposal: BRegPreparedProposal declare const recoveredAction: BRegRecoveredAction declare const recoveredCreate: BRegRecoveredCreate diff --git a/crates/registry-breg-client-node/__test__/proposal-exact-json.test.js b/crates/registry-breg-client-node/__test__/proposal-exact-json.test.js new file mode 100644 index 0000000000..e99796ef71 --- /dev/null +++ b/crates/registry-breg-client-node/__test__/proposal-exact-json.test.js @@ -0,0 +1,83 @@ +'use strict'; +const assert = require('node:assert/strict'); +const http = require('node:http'); +const { test } = require('node:test'); +const { BaseRegistryClient, BRegPreparedProposal } = process.env.BREG_CLIENT_PACKAGE + ? require(process.env.BREG_CLIENT_PACKAGE).breg : require('..'); + +const id = '00000000-0000-4000-8000-000000000001'; +const revision = `sha256:${'a'.repeat(64)}`; +const metadata = {id: 'proposal-json', version: '1', revision, metadataVersion: '2', recordTypes: [], operations: [], + proposals: {method: 'GET', path: '/v1/proposals', accessProfiles: ['author'], + actions: [{actionId: 'correct', accessProfile: 'author', operations: ['get', 'list'], readableInputs: [], readableContextFields: []}], + get: {method: 'GET', path: '/v1/proposals/{proposal_id}', accessProfiles: ['author']}}}; +const proposal = {id, actionId: 'correct', actionRevision: revision, submissionVersion: 1, revision: 1, state: 'draft', links: { + self: {method: 'GET', path: `/v1/proposals/${id}`, accessProfile: 'author', operation: 'get'}, + edit: {method: 'POST', path: `/v1/proposals/${id}/edit`, accessProfile: 'author', operation: 'edit', ifMatch: '"draft-condition"'}, +}}; +const inputJson = '{"nullable":null,"nested":{"wide":9223372036854775807,"decimal":"0.7500","values":[9223372036854775807,null,{"amount":"0.7500"}]}}'; + +test('exact Proposal JSON methods preserve nested values and recovery authority through native HTTP', async () => { + const requests = []; + let current = JSON.stringify(proposal).replace('"links":', `"input":${inputJson},"links":`); + const server = http.createServer(async (request, response) => { + let body = ''; for await (const chunk of request) body += chunk; + requests.push({url: request.url, body, headers: request.headers}); + response.writeHead(200, {'content-type': 'application/json', 'cache-control': 'no-store', vary: 'authorization, accept', + traceparent: '00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01'}); + if (request.url.startsWith('/tenant/v1/registry')) return response.end(JSON.stringify(metadata)); + if (request.url.startsWith('/tenant/v1/proposals?')) return response.end(`{"items":[${current}],"nextCursor":"next-page"}`); + if (request.url.includes('/edit?')) { + current = current.replace('"revision":1', '"revision":2').replace(inputJson, body.slice('{"input":'.length, -1)); + } + response.end(current); + }); + await new Promise(resolve => server.listen(0, '127.0.0.1', resolve)); + try { + const client = new BaseRegistryClient({baseUrl: `http://127.0.0.1:${server.address().port}/tenant/`}); + assert.equal(typeof client.prepareProposalJson, 'function'); + assert.equal(typeof client.listProposalsJson, 'function'); + const contract = await client.registryContract('author'); + const collection = contract.selectProposals('author'); + const page = await client.listProposalsJson(collection, '{"action":"correct","limit":1}'); + assert.equal(page.nextCursor, 'next-page'); + assert.match(page.items[0].inputJson, /9223372036854775807/); + assert.match(page.items[0].inputJson, /"decimal":"0.7500"/); + const url = new URL(requests.at(-1).url, 'http://fixture.invalid'); + assert.equal(url.pathname, '/tenant/v1/proposals'); + assert.equal(url.searchParams.get('accessProfile'), 'author'); + assert.equal(url.searchParams.get('action'), 'correct'); + assert.equal(url.searchParams.get('limit'), '1'); + const draft = page.items[0]; + const before = requests.length; + for (const body of ['{"input":{"wide":1,"wide":2}}', '{"input":{"wide":1e9999}}', '{"input":[]}', '[]']) { + assert.throws(() => client.prepareProposalJson(draft, 'edit', body, 'invalid'), error => error.kind === 'invalid-request' && !error.outcomeUnknown); + } + assert.throws(() => client.prepareProposalJson(draft, 'apply', '{}', 'illegal-transition'), error => error.kind === 'invalid-request'); + assert.throws(() => client.prepareProposal(draft, 'edit', {input: {wide: Number.MAX_SAFE_INTEGER + 1}}, 'unsafe'), error => error.kind === 'invalid-request'); + for (const query of ['{"limit":1,"limit":2}', '{"limit":0}', '{"unknown":true}', '{"limit":"one"}']) { + await assert.rejects(client.listProposalsJson(collection, query), error => error.kind === 'invalid-request', query); + } + assert.equal(requests.length, before, 'invalid JSON, query, structured unsafe numbers and transitions fail before I/O'); + assert.throws(() => client.prepareProposalJson(draft, 'edit', `{"input":${inputJson}}`, 'inexact-binary64'), error => error.kind === 'invalid-request'); + const exactEditInputJson = inputJson.replaceAll('9223372036854775807', '9007199254740992'); + const attempt = client.prepareProposalJson(draft, 'edit', `{"input":${exactEditInputJson}}`, 'exact-edit-key'); + const bytes = attempt.toBytes(); + const restored = BRegPreparedProposal.fromBytes(bytes); + await assert.rejects(client.executeProposal(restored), error => error.kind === 'invalid-request'); + assert.equal(requests.length, before, 'persisted evidence requires fresh matching Proposal authority'); + const recovered = client.recoverProposal(await client.readProposal(draft), restored); + assert.deepEqual(recovered.toBytes(), bytes); + const edited = await client.executeProposal(recovered); + assert.match(edited.inputJson, /9007199254740992/); + const sent = requests.at(-1); + assert.equal(sent.url, `/tenant/v1/proposals/${id}/edit?accessProfile=author`); + assert.equal(sent.headers['idempotency-key'], 'exact-edit-key'); + assert.equal(sent.headers['if-match'], '"draft-condition"'); + assert.match(sent.body, /"wide":9007199254740992/); + assert.match(sent.body, /"decimal":"0.7500"/); + assert.match(sent.body, /"values":\[9007199254740992,null,\{"amount":"0.7500"\}\]/); + assert.equal(JSON.parse(sent.body).input.nullable, null); + assert.ok(!Object.hasOwn(JSON.parse(sent.body).input, 'absent')); + } finally { await new Promise(resolve => server.close(resolve)); } +}); diff --git a/crates/registry-breg-client-node/client.d.ts b/crates/registry-breg-client-node/client.d.ts index 33d4fdd8d3..f9f72a039a 100644 --- a/crates/registry-breg-client-node/client.d.ts +++ b/crates/registry-breg-client-node/client.d.ts @@ -887,6 +887,8 @@ export declare class BaseRegistryClient { /** Read one retained submission version under the access profile of the Proposal's self link. */ readProposalSubmission(proposal: BRegProposal, version: number): Promise> listProposals(collection: BRegProposalCollection, query: JsonObject): Promise + /** Exact JSON query; retains the metadata-selected collection and bounded pagination. */ + listProposalsJson(collection: BRegProposalCollection, queryJson: string): Promise /** * Bind an available transition without I/O. Throws locally when the operation * is not a legal transition from the Proposal's observed state; `cancel` is @@ -895,6 +897,8 @@ export declare class BaseRegistryClient { * exercise the server's terminal-state refusal. */ prepareProposal(proposal: BRegProposal, operation: BRegProposalTransition, body: JsonObject, key: string): BRegPreparedProposal + /** Exact JSON body; preserves integer values and the same lifecycle authority and recovery contract. */ + prepareProposalJson(proposal: BRegProposal, operation: BRegProposalTransition, bodyJson: string, key: string): BRegPreparedProposal recoverProposal(proposal: BRegProposal, attempt: BRegPreparedProposal): BRegPreparedProposal executeProposal(attempt: BRegPreparedProposal): Promise constructor(config: BaseRegistryClientConfig) diff --git a/crates/registry-breg-client-node/client.js b/crates/registry-breg-client-node/client.js index f985ff981a..739c86401e 100644 --- a/crates/registry-breg-client-node/client.js +++ b/crates/registry-breg-client-node/client.js @@ -232,7 +232,7 @@ for (const [method, jsonIndexes, requiredIndexes] of [ ['invokeAction', [1], [1]], ['executeRecoveredAction'], ['executeRecoveredProposalStart'], ['executeRecoveredCreate'], ['patchRecord', [3], [3]], ['batchRecords', [1], [1]], ['tombstoneRecord'], - ['startProposal', [1], [1]], ['readProposal'], ['readProposalSubmission'], ['getProposal'], ['listProposals', [1], [1]], ['executeProposal'], + ['startProposal', [1], [1]], ['readProposal'], ['readProposalSubmission'], ['getProposal'], ['listProposals', [1], [1]], ['executeProposal'], ['listProposalsJson'], ['downloadProposalAttachment'], ['uploadProposalAttachment'], ['deleteProposalAttachment'], ['readProposalReviewStatus'], ['readProposalReviewContext'], ['readProposalReviewContextBatch', [1], [1]], @@ -256,7 +256,7 @@ for (const [method, jsonIndexes, requiredIndexes] of [ ['prepareAction', [1], [1]], ['prepareActionJson'], ['recoverAction', [2], [2]], ['recoverActionJson'], ['prepareCreate', [1], [1]], ['prepareCreateJson'], ['recoverCreate'], - ['prepareProposal', [2], [2]], ['recoverProposal'], + ['prepareProposal', [2], [2]], ['prepareProposalJson'], ['recoverProposal'], ]) { const original = native.BaseRegistryClient.prototype[method]; native.BaseRegistryClient.prototype[method] = function (...args) { diff --git a/crates/registry-breg-client-node/index.d.ts b/crates/registry-breg-client-node/index.d.ts index 7c138c6de3..4ecc3d5bad 100644 --- a/crates/registry-breg-client-node/index.d.ts +++ b/crates/registry-breg-client-node/index.d.ts @@ -63,6 +63,10 @@ export declare class BaseRegistryClient { deleteProposalAttachment(proposal: BRegProposal, slot: string, key: string): Promise listProposals(collection: BRegProposalCollection, query: any): Promise prepareProposal(proposal: BRegProposal, operation: string, body: any, key: string): BRegPreparedProposal + /** Prepare a transition from exact JSON through the same lifecycle authority. */ + prepareProposalJson(proposal: BRegProposal, operation: string, bodyJson: string, key: string): BRegPreparedProposal + /** List through the same metadata-selected collection with an exact JSON query. */ + listProposalsJson(collection: BRegProposalCollection, queryJson: string): Promise recoverProposal(proposal: BRegProposal, attempt: BRegPreparedProposal): BRegPreparedProposal executeProposal(attempt: BRegPreparedProposal): Promise /** Fetch opaque target conditions for one metadata-selected action. */ diff --git a/crates/registry-breg-client-node/src/lib.rs b/crates/registry-breg-client-node/src/lib.rs index fd356ad95a..a7c4848eb6 100644 --- a/crates/registry-breg-client-node/src/lib.rs +++ b/crates/registry-breg-client-node/src/lib.rs @@ -3393,6 +3393,29 @@ impl BaseRegistryClient { .map_err(client_error) } + /// Prepare a transition from exact JSON through the same lifecycle authority. + #[napi] + pub fn prepare_proposal_json( + &self, + proposal: &Proposal, + operation: String, + body_json: String, + key: String, + ) -> Result { + self.prepare_proposal(proposal, operation, exact_input(&body_json)?, key) + } + + /// List through the same metadata-selected collection with an exact JSON query. + #[napi] + pub async fn list_proposals_json( + &self, + collection: &ProposalCollection, + query_json: String, + ) -> Result { + self.list_proposals(collection, exact_input(&query_json)?) + .await + } + #[napi] pub fn recover_proposal( &self, diff --git a/crates/registry-breg-client/README.md b/crates/registry-breg-client/README.md index b3ae1f9064..fe7c5992c1 100644 --- a/crates/registry-breg-client/README.md +++ b/crates/registry-breg-client/README.md @@ -56,6 +56,11 @@ client's configured credential unchanged. Each derived value owns its token, so different callers can use the same base client concurrently without a mutable credential slot. Keep it within the inbound request that supplied the token. +Use `client.with_maximum_response_bytes(limit)?` to derive a client with a +separate response-body budget for a particular exchange. It reuses the same +credential provider, connection pool and source binding, and leaves the original +client's response limit unchanged. The limit must be greater than zero. + ## Read records ```rust,no_run diff --git a/crates/registry-breg-client/src/client.rs b/crates/registry-breg-client/src/client.rs index b7e347dfb2..7fcaac2431 100644 --- a/crates/registry-breg-client/src/client.rs +++ b/crates/registry-breg-client/src/client.rs @@ -72,6 +72,20 @@ impl BaseRegistryClient { } } + /// Derive a client with a different finite response-body limit, reusing the + /// same credential provider, connection pool, and source binding. The + /// original client and all other transport policy remain unchanged. + pub fn with_maximum_response_bytes( + &self, + maximum: u64, + ) -> Result { + let config = self.config.clone().with_maximum_response_bytes(maximum); + config.validate()?; + let mut transport = self.transport.clone(); + transport.maximum_response_bytes = maximum; + Ok(Self { config, transport }) + } + /// Unauthenticated liveness probe. Configured bearer credentials are never /// acquired or sent. pub async fn health(&self) -> Result, BaseRegistryClientError> { diff --git a/crates/registry-breg-client/src/metadata.rs b/crates/registry-breg-client/src/metadata.rs index 71f85abad5..f5d913988a 100644 --- a/crates/registry-breg-client/src/metadata.rs +++ b/crates/registry-breg-client/src/metadata.rs @@ -1796,7 +1796,10 @@ fn action_field_type(value: Value) -> Result<(), BRegMetadataError> { } "vocabulary-code" => { bounded_string(required(&mut field_type, "vocabulary")?)?; - let values = identifier_array(required(&mut field_type, "values")?)?; + let values = array(required(&mut field_type, "values")?)? + .into_iter() + .map(bounded_short_text) + .collect::, _>>()?; if values.is_empty() || ensure_unique(values.iter().map(String::as_str)).is_err() { return Err(metadata_error(BRegMetadataErrorKind::Shape)); } diff --git a/crates/registry-breg-client/src/metadata_vocabulary_tests.rs b/crates/registry-breg-client/src/metadata_vocabulary_tests.rs index a310911441..f99a533265 100644 --- a/crates/registry-breg-client/src/metadata_vocabulary_tests.rs +++ b/crates/registry-breg-client/src/metadata_vocabulary_tests.rs @@ -111,6 +111,57 @@ fn action_field_type_vocabulary_accepts_every_bounded_engine_string() { } } +#[test] +fn action_vocabulary_codes_follow_engine_code_grammar() { + for codes in [ + json!(["A-report", "B-report", "C-report"]), + json!(["123", "two words", "สถานะ/許可"]), + json!(["x".repeat(128), "é".repeat(64)]), + ] { + let mut value = metadata("status"); + value["actions"][0]["inputs"][0]["fieldType"]["values"] = codes.clone(); + value["actions"][0]["inputs"][0]["schema"]["enum"] = codes.clone(); + let parsed = parse(&value).unwrap(); + let action = parsed.select_action("update-status", "writer").unwrap(); + assert_eq!(action.inputs()[0].field_type()["values"], codes); + for code in codes.as_array().unwrap() { + crate::BRegActionInvocationRequest::new( + &action, + Map::from_iter([("status".to_owned(), code.clone())]), + None, + ) + .unwrap(); + } + } +} + +#[test] +fn invalid_action_vocabulary_codes_never_promote_to_authority() { + for codes in [ + json!([]), + json!([""]), + json!(["A-report", "A-report"]), + json!(["line one\nline two"]), + json!(["nul\0"]), + json!(["x".repeat(129)]), + json!(["é".repeat(65)]), + json!([17]), + json!("A-report"), + ] { + let mut value = metadata("status"); + value["actions"][0]["inputs"][0]["fieldType"]["values"] = codes; + let parsed = parse(&value).unwrap(); + assert_eq!(parsed.actions().len(), 1); + assert_eq!( + parsed + .select_action("update-status", "writer") + .unwrap_err() + .kind(), + BRegMetadataSelectionErrorKind::ContractMismatch + ); + } +} + #[test] fn vocabulary_strings_retain_the_metadata_string_bound() { let maximum = "v".repeat(64 * 1024); diff --git a/crates/registry-breg-client/tests/action_recovery_registry_revision.rs b/crates/registry-breg-client/tests/action_recovery_registry_revision.rs index 6007ffc8b8..5117db3b89 100644 --- a/crates/registry-breg-client/tests/action_recovery_registry_revision.rs +++ b/crates/registry-breg-client/tests/action_recovery_registry_revision.rs @@ -95,6 +95,80 @@ async fn handler(State(state): State, _request: Request) -> Res response } +#[tokio::test] +async fn caller_metadata_vocabulary_codes_prepare_and_recover_exactly() { + let mut metadata = action_metadata(REVISION_A); + metadata["actions"][0]["inputs"][0]["fieldType"] = json!({ + "type": "vocabulary-code", "vocabulary": "report-type", + "values": ["A-report", "B-report", "C-report"] + }); + metadata["actions"][0]["inputs"][0]["schema"] = json!({ + "type": "string", "enum": ["A-report", "B-report", "C-report"] + }); + let served = Arc::new(AtomicUsize::new(0)); + let state = MockState { + responses: Arc::new(Mutex::new(VecDeque::from([metadata]))), + served: served.clone(), + }; + let listener = TcpListener::bind("127.0.0.1:0").await.unwrap(); + let address = listener.local_addr().unwrap(); + let server = tokio::spawn(async move { + axum::serve( + listener, + Router::new().fallback(any(handler)).with_state(state), + ) + .await + .unwrap(); + }); + let tokens = Arc::new(StaticToken(AtomicUsize::new(0))); + let client = BaseRegistryClient::new( + BaseRegistryClientConfig::new( + Url::parse(&format!("http://{address}/tenant/base")).unwrap(), + ) + .with_token_provider(tokens.clone()), + ) + .unwrap(); + let metadata = client + .registry_contract(Some("preparer")) + .await + .unwrap() + .value; + assert!(metadata + .select_action("incorporate-company", "other-profile") + .is_err()); + let action = metadata + .select_action("incorporate-company", "preparer") + .unwrap(); + let key = BRegIdempotencyKey::parse("report-1").unwrap(); + for code in ["A-report", "B-report", "C-report"] { + let inputs = Map::from_iter([("reference".to_owned(), json!(code))]); + let request = BRegActionInvocationRequest::new(&action, inputs.clone(), None).unwrap(); + let prepared = client.prepare_action(&action, &request, &key).unwrap(); + let saved: Value = serde_json::from_slice(prepared.as_bytes()).unwrap(); + let body: Value = serde_json::from_str(saved["body"].as_str().unwrap()).unwrap(); + assert_eq!(body["input"]["reference"], code); + let recovered = client + .recover_action(&action, &prepared, &inputs, &key) + .unwrap(); + assert_eq!( + client + .prepare_action(&action, &recovered, &key) + .unwrap() + .as_bytes(), + prepared.as_bytes() + ); + } + assert!(BRegActionInvocationRequest::new( + &action, + Map::from_iter([("reference".to_owned(), json!("a-report"))]), + None, + ) + .is_err()); + assert_eq!(served.load(Ordering::SeqCst), 1); + assert_eq!(tokens.0.load(Ordering::SeqCst), 1); + server.abort(); +} + #[tokio::test] async fn saved_command_refuses_after_registry_revision_change() { let served = Arc::new(AtomicUsize::new(0)); diff --git a/crates/registry-breg-client/tests/http_boundary.rs b/crates/registry-breg-client/tests/http_boundary.rs index 940848eae3..af46af8971 100644 --- a/crates/registry-breg-client/tests/http_boundary.rs +++ b/crates/registry-breg-client/tests/http_boundary.rs @@ -983,3 +983,28 @@ async fn redirects_with_bearer_and_oversize_bodies_are_refused_without_retry() { } )); } + +#[tokio::test] +async fn derived_response_limits_retain_credentials_and_leave_the_original_bound_unchanged() { + let provider = Arc::new(CountingToken(AtomicUsize::new(0))); + let (client, requests) = test_client(Mode::Happy, Some(provider.clone()), 1).await; + assert!(client.with_maximum_response_bytes(0).is_err()); + assert_eq!(provider.0.load(Ordering::SeqCst), 0); + assert!(requests.lock().unwrap().is_empty()); + let metadata_client = client.with_maximum_response_bytes(1024).unwrap(); + assert!(metadata_client + .registry_metadata(Some("reviewer")) + .await + .is_ok()); + assert!(matches!( + client.registry_metadata(Some("reviewer")).await, + Err(BaseRegistryClientError::Transport { + kind: TransportKind::ResponseTooLarge + }) + )); + assert_eq!(provider.0.load(Ordering::SeqCst), 2); + let requests = requests.lock().unwrap(); + assert_eq!(requests.len(), 2); + assert_eq!(requests[0].uri, requests[1].uri); + assert_eq!(requests[0].authorization, requests[1].authorization); +} diff --git a/crates/registry-coordinator/src/adapters.rs b/crates/registry-coordinator/src/adapters.rs index 3251562e9a..0c6fe6823a 100644 --- a/crates/registry-coordinator/src/adapters.rs +++ b/crates/registry-coordinator/src/adapters.rs @@ -6,6 +6,7 @@ use std::{collections::BTreeMap, path::Path, sync::Arc, time::Duration}; use async_trait::async_trait; use registry_breg_client::{ BRegRecordOptions, BaseRegistryClient, BaseRegistryClientConfig, BaseRegistryClientError, + TransportKind, MAX_BREG_METADATA_BYTES, }; use registry_casework_client::{CaseworkClient, CaseworkClientConfig, CaseworkTaskAssertionSource}; use registry_messaging_client::{ @@ -141,6 +142,14 @@ fn breg_client( ) } +// Caller-filtered control metadata may describe many unrelated operations. +// Keep its native finite ceiling separate from business response payloads. +pub(crate) fn breg_metadata_client( + client: &BaseRegistryClient, +) -> std::result::Result { + client.with_maximum_response_bytes(MAX_BREG_METADATA_BYTES as u64) +} + impl HttpAdapters { pub fn load(path: &Path) -> Result { Self::new(&RuntimeConfig::load(path)?) @@ -496,6 +505,9 @@ async fn read_record_v2( pub(crate) fn read_failure(error: BaseRegistryClientError) -> CallOutcome { match error { BaseRegistryClientError::Token(error) => token_failure(&error), + BaseRegistryClientError::Transport { + kind: TransportKind::ResponseTooLarge, + } => refused("invalid-response"), BaseRegistryClientError::Transport { .. } => retryable("transport-unavailable"), error if error.status() == Some(429) => retryable("rate-limited"), BaseRegistryClientError::Problem { diff --git a/crates/registry-coordinator/src/breg_action.rs b/crates/registry-coordinator/src/breg_action.rs index 673a79ea40..5e73520b73 100644 --- a/crates/registry-coordinator/src/breg_action.rs +++ b/crates/registry-coordinator/src/breg_action.rs @@ -8,7 +8,7 @@ use registry_breg_client::{ BRegActionBinding, BRegActionInvocationRequest, BRegActionMode, BRegActionTargetConditionsRequest, BRegIdempotencyKey, BRegPreparedAction, BRegProblemCode, - BaseRegistryClient, BaseRegistryClientError, + BaseRegistryClient, BaseRegistryClientError, TransportKind, }; use serde::{Deserialize, Serialize}; use serde_json::{Map, Value}; @@ -87,6 +87,9 @@ pub(crate) fn failure(error: BaseRegistryClientError, mutation: bool) -> CallOut } match error { BaseRegistryClientError::Token(error) => token_failure(&error), + BaseRegistryClientError::Transport { + kind: TransportKind::ResponseTooLarge, + } => refused("invalid-response"), BaseRegistryClientError::Transport { .. } => retryable("transport-unavailable"), error if error.status() == Some(429) => retryable("rate-limited"), BaseRegistryClientError::Problem { @@ -113,7 +116,8 @@ async fn binding( operation: Operation, expected: &ActionContract, ) -> Result { - let metadata = client + let metadata = crate::adapters::breg_metadata_client(client) + .map_err(|error| failure(error, false))? .registry_contract(Some(profile)) .await .map_err(|error| failure(error, false))?; diff --git a/crates/registry-coordinator/src/breg_proposal.rs b/crates/registry-coordinator/src/breg_proposal.rs index 44f930e5a7..2fd09e4ca6 100644 --- a/crates/registry-coordinator/src/breg_proposal.rs +++ b/crates/registry-coordinator/src/breg_proposal.rs @@ -153,7 +153,8 @@ async fn current( expected: &ActionContract, proposal_id: Uuid, ) -> Result { - let metadata = client + let metadata = crate::adapters::breg_metadata_client(client) + .map_err(Reading::Failed)? .registry_contract(Some(profile)) .await .map_err(Reading::Failed)?; diff --git a/crates/registry-coordinator/tests/breg_action_adapter.rs b/crates/registry-coordinator/tests/breg_action_adapter.rs index ab575bbbf6..700e77567c 100644 --- a/crates/registry-coordinator/tests/breg_action_adapter.rs +++ b/crates/registry-coordinator/tests/breg_action_adapter.rs @@ -568,3 +568,139 @@ async fn configured_adapter_requires_preparation_and_never_reconciles_by_sending assert_eq!(server.received_requests().await.unwrap().len(), count); issuer.stop().await; } + +fn bounded_client(server: &MockServer, token: Arc) -> BaseRegistryClient { + BaseRegistryClient::new( + BaseRegistryClientConfig::new(format!("{}/tenant/base/", server.uri()).parse().unwrap()) + .with_token_provider(token) + .with_maximum_response_bytes(65_536) + .with_maximum_mutation_retries(0), + ) + .unwrap() +} + +fn expanded_metadata() -> Value { + let mut document = metadata(); + document["additionalDescriptions"] = json!(["m".repeat(40_000), "n".repeat(40_000)]); + assert!(serde_json::to_vec(&document).unwrap().len() > 65_536); + document +} + +#[tokio::test] +async fn metadata_has_a_separate_finite_budget_without_changing_frozen_action_authority() { + let server = MockServer::start().await; + let current = authority(&server).await; + *current.lock().unwrap() = expanded_metadata(); + Mock::given(method("POST")) + .and(path("/tenant/base/v1/actions/update-item")) + .and(query_param("accessProfile", "writer")) + .respond_with(response(receipt())) + .expect(1) + .mount(&server) + .await; + let tokens = Arc::new(CountingToken::default()); + let client = bounded_client(&server, tokens.clone()); + let command = request(); + let prepared = prepare(&client, "writer", &command) + .await + .unwrap_or_else(|_| panic!("valid metadata above the business-response bound prepares")); + let saved = prepared.clone(); + match execute(&client, "writer", &command, &prepared).await { + CallOutcome::Success(value) => assert_eq!(value, receipt()), + _ => panic!("the same source-bound Action executes with the business response limit"), + } + assert_eq!(prepared, saved); + assert_eq!(tokens.0.load(Ordering::SeqCst), 4); + let requests = server.received_requests().await.unwrap(); + assert_eq!(requests.len(), 4); + for request in &requests { + assert_eq!( + request.headers["authorization"], + "Bearer synthetic-action-token" + ); + assert!(request + .url + .query_pairs() + .any(|(key, value)| key == "accessProfile" && value == "writer")); + } + let sent = requests.last().unwrap(); + assert_eq!(sent.headers["idempotency-key"], "durable-action-key"); + assert_eq!( + serde_json::from_slice::(&sent.body).unwrap(), + json!({ + "input":{"targetId":RECORD,"label":"Original"}, + "preconditions":{"targetId":{"ifMatch":CONDITION}} + }) + ); + assert_eq!( + command.operation_contract.unwrap().action_revision, + FINGERPRINT + ); +} + +#[tokio::test] +async fn metadata_above_the_native_metadata_ceiling_is_a_terminal_preparation_refusal() { + let server = MockServer::start().await; + let mut document = metadata(); + document["additionalDescriptions"] = json!(vec!["m".repeat(65_536); 129]); + assert!( + serde_json::to_vec(&document).unwrap().len() + > registry_breg_client::MAX_BREG_METADATA_BYTES + ); + Mock::given(method("GET")) + .and(path("/tenant/base/v1/registry")) + .respond_with(response(document)) + .expect(1) + .mount(&server) + .await; + let client = bounded_client(&server, Arc::new(CountingToken::default())); + match prepare(&client, "writer", &request()).await { + Err(outcome) => refusal(outcome, "invalid-response"), + Ok(_) => panic!("overlarge metadata cannot prepare an Action"), + } + assert_eq!(server.received_requests().await.unwrap().len(), 1); +} + +#[tokio::test] +async fn metadata_budget_never_widens_target_condition_response_bodies() { + let server = MockServer::start().await; + Mock::given(method("GET")) + .and(path("/tenant/base/v1/registry")) + .respond_with(response(expanded_metadata())) + .mount(&server) + .await; + Mock::given(method("POST")) + .and(path( + "/tenant/base/v1/actions/update-item/target-conditions", + )) + .respond_with(response(json!({"oversized-condition": "x".repeat(65_536)}))) + .mount(&server) + .await; + let client = bounded_client(&server, Arc::new(CountingToken::default())); + match prepare(&client, "writer", &request()).await { + Err(outcome) => refusal(outcome, "invalid-response"), + Ok(_) => panic!("business responses retain the 64 KiB limit"), + } + assert_eq!(server.received_requests().await.unwrap().len(), 2); +} + +#[tokio::test] +async fn overlarge_mutation_responses_remain_uncertain_after_dispatch() { + let server = MockServer::start().await; + authority(&server).await; + Mock::given(method("POST")) + .and(path("/tenant/base/v1/actions/update-item")) + .respond_with(response(json!({"oversized-result": "x".repeat(65_536)}))) + .expect(1) + .mount(&server) + .await; + let client = bounded_client(&server, Arc::new(CountingToken::default())); + let command = request(); + let prepared = prepare(&client, "writer", &command) + .await + .unwrap_or_else(|_| panic!("valid preparation")); + match execute(&client, "writer", &command, &prepared).await { + CallOutcome::Uncertain { code } => assert_eq!(code, "transport-uncertain"), + _ => panic!("an oversized mutation answer cannot prove no effect"), + } +} diff --git a/crates/registry-coordinator/tests/breg_proposal_adapter.rs b/crates/registry-coordinator/tests/breg_proposal_adapter.rs index 9135f5d4fd..94a05b6f8a 100644 --- a/crates/registry-coordinator/tests/breg_proposal_adapter.rs +++ b/crates/registry-coordinator/tests/breg_proposal_adapter.rs @@ -152,10 +152,14 @@ struct Fixture { impl Fixture { async fn start() -> Self { + Self::with_metadata(metadata()).await + } + + async fn with_metadata(metadata: Value) -> Self { let server = MockServer::start().await; Mock::given(method("GET")) .and(path("/tenant/base/v1/registry")) - .respond_with(response(200, metadata())) + .respond_with(response(200, metadata)) .mount(&server) .await; let current = Arc::new(Mutex::new(Current::Proposal(proposal("draft", 1, 1)))); @@ -673,3 +677,30 @@ async fn each_answered_follow_read_records_what_the_proposal_showed() { ); fixture.issuer.stop().await; } + +#[tokio::test] +async fn proposal_get_uses_the_separate_metadata_budget_and_retains_its_business_body_limit() { + let mut document = metadata(); + document["additionalDescriptions"] = json!(["m".repeat(40_000), "n".repeat(40_000)]); + let fixture = Fixture::with_metadata(document).await; + let read = command(Operation::ReadProposal, json!({"proposalId":ID}), None); + assert_eq!( + success(fixture.adapters.call(&read).await), + receipt("draft", 1) + ); + let mut oversized = proposal("draft", 1, 1); + oversized["input"]["label"] = json!("x".repeat(65_536)); + fixture.answer(Current::Proposal(oversized)); + match fixture.adapters.call(&read).await { + CallOutcome::Refused { code } => assert_eq!(code, "invalid-response"), + _ => panic!("an oversized Proposal read is terminal and never enlarges its budget"), + } + assert!(fixture + .server + .received_requests() + .await + .unwrap() + .iter() + .all(|request| request.method == "GET")); + fixture.issuer.stop().await; +} diff --git a/crates/registry-coordinator/tests/read_in_force_adapter.rs b/crates/registry-coordinator/tests/read_in_force_adapter.rs index c6b80e6c0b..a129db6c7f 100644 --- a/crates/registry-coordinator/tests/read_in_force_adapter.rs +++ b/crates/registry-coordinator/tests/read_in_force_adapter.rs @@ -328,3 +328,16 @@ async fn unknown_input_members_are_refused() { assert_eq!(refusal_code(&outcome), "invalid-command"); assert_eq!(count, 0); } + +#[tokio::test] +async fn an_oversized_record_response_is_terminal_instead_of_retryable() { + let (outcome, count) = run( + ResponseTemplate::new(200) + .insert_header("traceparent", TRACE) + .set_body_raw("x".repeat(65_537), "application/json"), + command(district(), "2026-06-05"), + ) + .await; + assert_eq!(count, 1); + assert_eq!(refusal_code(&outcome), "invalid-response"); +} diff --git a/crates/registry-stack-client-node/breg/client.d.ts b/crates/registry-stack-client-node/breg/client.d.ts index 33d4fdd8d3..f9f72a039a 100644 --- a/crates/registry-stack-client-node/breg/client.d.ts +++ b/crates/registry-stack-client-node/breg/client.d.ts @@ -887,6 +887,8 @@ export declare class BaseRegistryClient { /** Read one retained submission version under the access profile of the Proposal's self link. */ readProposalSubmission(proposal: BRegProposal, version: number): Promise> listProposals(collection: BRegProposalCollection, query: JsonObject): Promise + /** Exact JSON query; retains the metadata-selected collection and bounded pagination. */ + listProposalsJson(collection: BRegProposalCollection, queryJson: string): Promise /** * Bind an available transition without I/O. Throws locally when the operation * is not a legal transition from the Proposal's observed state; `cancel` is @@ -895,6 +897,8 @@ export declare class BaseRegistryClient { * exercise the server's terminal-state refusal. */ prepareProposal(proposal: BRegProposal, operation: BRegProposalTransition, body: JsonObject, key: string): BRegPreparedProposal + /** Exact JSON body; preserves integer values and the same lifecycle authority and recovery contract. */ + prepareProposalJson(proposal: BRegProposal, operation: BRegProposalTransition, bodyJson: string, key: string): BRegPreparedProposal recoverProposal(proposal: BRegProposal, attempt: BRegPreparedProposal): BRegPreparedProposal executeProposal(attempt: BRegPreparedProposal): Promise constructor(config: BaseRegistryClientConfig) diff --git a/crates/registry-stack-client-node/breg/client.js b/crates/registry-stack-client-node/breg/client.js index f985ff981a..739c86401e 100644 --- a/crates/registry-stack-client-node/breg/client.js +++ b/crates/registry-stack-client-node/breg/client.js @@ -232,7 +232,7 @@ for (const [method, jsonIndexes, requiredIndexes] of [ ['invokeAction', [1], [1]], ['executeRecoveredAction'], ['executeRecoveredProposalStart'], ['executeRecoveredCreate'], ['patchRecord', [3], [3]], ['batchRecords', [1], [1]], ['tombstoneRecord'], - ['startProposal', [1], [1]], ['readProposal'], ['readProposalSubmission'], ['getProposal'], ['listProposals', [1], [1]], ['executeProposal'], + ['startProposal', [1], [1]], ['readProposal'], ['readProposalSubmission'], ['getProposal'], ['listProposals', [1], [1]], ['executeProposal'], ['listProposalsJson'], ['downloadProposalAttachment'], ['uploadProposalAttachment'], ['deleteProposalAttachment'], ['readProposalReviewStatus'], ['readProposalReviewContext'], ['readProposalReviewContextBatch', [1], [1]], @@ -256,7 +256,7 @@ for (const [method, jsonIndexes, requiredIndexes] of [ ['prepareAction', [1], [1]], ['prepareActionJson'], ['recoverAction', [2], [2]], ['recoverActionJson'], ['prepareCreate', [1], [1]], ['prepareCreateJson'], ['recoverCreate'], - ['prepareProposal', [2], [2]], ['recoverProposal'], + ['prepareProposal', [2], [2]], ['prepareProposalJson'], ['recoverProposal'], ]) { const original = native.BaseRegistryClient.prototype[method]; native.BaseRegistryClient.prototype[method] = function (...args) { diff --git a/crates/registry-stack-client-node/breg/index.d.ts b/crates/registry-stack-client-node/breg/index.d.ts index fed59b6a27..3e671bf181 100644 --- a/crates/registry-stack-client-node/breg/index.d.ts +++ b/crates/registry-stack-client-node/breg/index.d.ts @@ -55,6 +55,10 @@ export declare class BaseRegistryClient { deleteProposalAttachment(proposal: BRegProposal, slot: string, key: string): Promise listProposals(collection: BRegProposalCollection, query: any): Promise prepareProposal(proposal: BRegProposal, operation: string, body: any, key: string): BRegPreparedProposal + /** Prepare a transition from exact JSON through the same lifecycle authority. */ + prepareProposalJson(proposal: BRegProposal, operation: string, bodyJson: string, key: string): BRegPreparedProposal + /** List through the same metadata-selected collection with an exact JSON query. */ + listProposalsJson(collection: BRegProposalCollection, queryJson: string): Promise recoverProposal(proposal: BRegProposal, attempt: BRegPreparedProposal): BRegPreparedProposal executeProposal(attempt: BRegPreparedProposal): Promise /** Fetch opaque target conditions for one metadata-selected action. */ diff --git a/products/coordinator/PRODUCT-CONTRACT.md b/products/coordinator/PRODUCT-CONTRACT.md index d2a69d4d57..f75cea3bda 100644 --- a/products/coordinator/PRODUCT-CONTRACT.md +++ b/products/coordinator/PRODUCT-CONTRACT.md @@ -82,6 +82,15 @@ downstream authority. Credentials are acquired for each attempt, and each receiv current policy. Waits, retries, restarts, and recovery never renew an approval or alter its original principal, resource, scopes, bounds, or deadline. +BReg caller-filtered contract metadata uses the native client's separate 8 MiB +metadata ceiling. The 64 KiB business-response budget still applies to records, +target conditions, Action results and Proposals. The metadata-only derived +client keeps the same credential provider, connection pool and source binding; +it does not change the pinned Action revision, profile, prepared command or key. +An oversized read or preparation response is a terminal `invalid-response` +refusal. An oversized answer after dispatching a mutation remains uncertain, +because the effect may already have committed. + ## Governed Actions `breg.invoke-action/v1` imports an exact Base Registry Engine (BReg) Action using `action.contract` and `action.id`. diff --git a/products/coordinator/SECURITY-REVIEW-NOTES.md b/products/coordinator/SECURITY-REVIEW-NOTES.md index d80683aebd..f0eecd62db 100644 --- a/products/coordinator/SECURITY-REVIEW-NOTES.md +++ b/products/coordinator/SECURITY-REVIEW-NOTES.md @@ -553,3 +553,34 @@ feature; the Rhai version is pinned exactly (`=1.27.0`), so the unstable surface cannot change under a routine update. The check is an authoring aid, not a security boundary: the engine still refuses any name it lacks when the Function runs. + +## BReg metadata and business response budgets + +### Threat and enforcement + +Applying the 64 KiB business-response ceiling to caller-filtered BReg control +metadata can prevent preparation for an otherwise valid Action. Treating that +oversize answer as a transient transport error repeats an unchanged failure. +Globally widening the response limit would instead admit larger business data. + +`adapters::breg_metadata_client` derives a client only for `registry_contract` +reads, using BReg's existing `MAX_BREG_METADATA_BYTES` ceiling (8 MiB). +`BaseRegistryClient::with_maximum_response_bytes` reuses the same immutable +credential provider, HTTP pool and source binding; the original 64 KiB client +still sends target-condition, record, Action and Proposal requests. +`breg_action::failure` and `adapters::read_failure` refuse oversized reads with +`invalid-response`. Mutation classification first preserves the BReg client's +unknown-outcome signal, so an oversized mutation answer remains uncertain. +No new transport retry, authority, key, condition or Action revision is created. + +### Tests and residuals + +`crates/registry-coordinator/tests/breg_action_adapter.rs` covers metadata above +64 KiB followed by an exact prepared Action, metadata beyond the 8 MiB ceiling, +an oversized target-condition response, and an oversized mutation answer. +`crates/registry-breg-client/tests/http_boundary.rs` covers independent derived +limits, unchanged credentials and original limits, and zero refusing before I/O. +The existing Action and Proposal adapter suites cover revision, profile and +recovery authority. These client HTTP fixtures do not establish database +transaction or deployed service behavior. An oversized mutation answer still +requires the existing same-command recovery or operator resolution.