Skip to content

Releases

v1.1.0

Choose a tag to compare

@legendko legendko released this 05 Nov 17:15

v1.1.0 lets a Broker answer an agent's free-text query from a catalog search the operator chooses, including an Elasticsearch index the operator already runs, and lets agents narrow that search with filters the deployment declares. Every edge package the publisher console hands out now carries a README with its deploy steps and the checks the console runs.

Upgrading from v1.0.0

  • No database migrations, and the protocol does not change. The release stays on FORA protocol v1.2.0. The Exchange and the edge worker behave as in v1.0.0.
  • Broker: BROKER_QUERY_DISCOVERY is replaced by BROKER_QUERY_PROVIDER. If your Broker ran query discovery with BROKER_QUERY_DISCOVERY=on, set BROKER_QUERY_PROVIDER=llm instead. BROKER_QUERY_CATALOG_FILE, BROKER_QUERY_MODEL and BROKER_QUERY_URI_SCHEME keep their meaning. The old setting is no longer read: a Broker that still sets only BROKER_QUERY_DISCOVERY starts with no catalog search and logs broker.query_discovery.disabled. BROKER_QUERY_PROVIDER=on stops the Broker at start-up. If you deploy with the Terraform compose-stack module or the demo and staging stacks, nothing changes for you: query_discovery works as before.
  • Identity. IDENTITY_MCP_SEARCH_FILTERS_SCHEMA (or its _FILE form) is new and optional. Leave it unset unless the Broker behind this service runs the elasticsearch provider. Unset, fora_discover checks no filter itself and passes search_filters to the Broker, as in v1.0.0.
  • Console. No setting is new or removed. CONSOLE_SUPPORT_EMAIL is now also written into the README of every edge package, so set it.
  • Terraform. The compose-stack module and the demo-aws and staging-aws stacks take a new optional elasticsearch_search object. No variable is removed. The aws-vm module has a new output, data_volume_name.

Highlights

  • Catalog search providers. BROKER_QUERY_PROVIDER selects one catalog search per Broker: none (the default, as before), llm (the former query discovery: a model extracts music tags from the query and matches them against the music feed held in memory) or elasticsearch. A provider that fails never falls back to another, and a configuration problem stops the Broker at start-up, naming the setting. Settings: src/broker/CONFIGURATION.md §7.
  • Elasticsearch catalog search. The Broker runs the index owner's search template, stored in the cluster (BROKER_ES_TEMPLATE_ID) or sent with each search from a file (BROKER_ES_TEMPLATE_FILE), and fills three parameters: query, filters and limit. It reads one URL from each hit at a configured path (BROKER_ES_HIT_URL_PATH), and each URL then takes the normal route through the publisher's discovery file and the Exchange's offers. The Broker calls only _search/template and _render/template, with Go's standard HTTP client and no Elasticsearch client library, so it works with Elasticsearch 6.x and later and with OpenSearch. It is tested on Elasticsearch 7.15.0. Authentication is api_key, basic or none, with no default. Plain http needs its own opt-in (BROKER_ES_ALLOW_HTTP), and both none and plain http log a warning at start-up. At start-up the Broker renders and runs the template once: credentials the cluster refuses stop the start, and an unreachable or misconfigured cluster logs a warning. A template file that inserts agent text unescaped ({{{ }}}, {{& }}, the join lambda, or changed delimiters) is refused. The guide for the index owner is src/broker/SEARCH-TEMPLATE.md, and a working template and filter schema to start from are in deploy/broker/. Design: ADR-030.
  • Declared search filters. A deployment declares the search_filters keys its template applies, and the format of each value, in a JSON Schema (BROKER_ES_FILTERS_SCHEMA or BROKER_ES_FILTERS_SCHEMA_FILE). The Broker checks every request against it before it searches: a key the schema does not declare is refused with UNIMPLEMENTED, and a value it refuses with INVALID_ARGUMENT, each naming the field search_filters.<key>. A filter is never dropped, and with no schema every filter is refused. The Identity service's fora_discover tool shows the same schema to agents as the input schema of search_filters (IDENTITY_MCP_SEARCH_FILTERS_SCHEMA), so an agent sees the accepted keys and formats before it calls. Settings: src/identity/CONFIGURATION.md.
  • A README in every edge package. Each edge package the console hands out now carries a README written for that domain: what is in the package, its values, links to the CDN vendor's pages, the deploy steps, and the three checks the console runs, numbered, each with the answer to expect. It ends with what verifies the domain and, when CONSOLE_SUPPORT_EMAIL is set, where to write for help.
  • Terraform. With elasticsearch_search set, the compose-stack module and the demo and staging stacks run the Broker on the elasticsearch provider. The module takes an https URL and a read-only API key, and writes the key, the template and the filter schema to the Broker's key directory as files, never into the compose file.
  • Testing. Integration tests run the provider against a real Elasticsearch 7.15.0 node, and the end-to-end stack runs a second Broker on the elasticsearch provider, with its own obligations.

Container images

Built from this tag for linux/amd64.

docker pull ghcr.io/fora-protocol/exchange:1.1.0
docker pull ghcr.io/fora-protocol/broker:1.1.0
docker pull ghcr.io/fora-protocol/identity:1.1.0
docker pull ghcr.io/fora-protocol/console:1.1.0
Image Digest
exchange sha256:c7f2d6b0a4b77b9f06da81fe746e4a1c90ed957d2d9b31319b2a0252d63502a9
broker sha256:db1f8b9ef210efe9a59deb7cbaebeb455d10c1df44409abf3544d1b68dba1cb7
identity sha256:7485ebdcc6258aae6f8b436ec51cf6cca5d5da7d20ebc194c7dbd54961e70097
console sha256:0ba0bbb031d426980152986ccd32e0c466d5c79b20f68a03f1727ccb2396f6fb

Each service's DEPLOYMENT.md and CONFIGURATION.md say how to run it: exchange, broker, identity, console.

Protocol

Unchanged since v1.0.0: FORA protocol v1.2.0 everywhere, as the Go module github.com/FORA-Protocol/protocol v1.2.0 for the services, @fora-protocol/sdk 1.2.0 for the edge, and fora-protocol-sdk 1.2.0 with the fora-protocol 1.2.0 models for the end-to-end tests.

Full Changelog: v1.0.0...v1.1.0

v1.0.0

Choose a tag to compare

@legendko legendko released this 30 Oct 16:19

v1.0.0 is the first release of the FORA reference implementation that is not a release candidate. It moves onto FORA protocol v1.2.0, lets an Exchange sell a licensing term only to subscribers who prove it with a verified delegation chain, and leaves a publisher's discovery file where the publisher keeps it: on their own site. The publisher console now takes a new publisher through four steps and saves their work as they go.

Upgrading from v1.0.0-rc.5

  • Protocol v1.2.0. Request signing does not change, so clients built on the v1.1.0 SDKs keep working. What changes is the delegation chain in Requester.delegation: it must follow the v1.2.0 delegation profile, and Delegation.token is at most 32768 bytes. Move agents and other clients to the v1.2.0 SDKs.
  • The edge no longer answers /.well-known/fora.json or /rsl.txt. It passes both addresses through to the publisher's origin, for every client. Before you deploy this release's edge, serve the discovery file from the origin (the fora.json the publisher console gives you), and the RSL file if you have one. The edge no longer reads PROVIDER, EXCHANGES_JSON, CATALOG_CONTRIBUTORS_JSON or RSL_BODY: a deployment that still sets them starts and ignores them. The domain-verification route /.well-known/fora-verify/<token> and its setting ACME_TOKENS_JSON are removed.
  • Terraform. The cloudflare-edge module no longer takes provider_domain, exchanges_json, rsl_body, acme_tokens_json or catalog_contributors_json: remove them from the module block. The edge stack drops the last four; its provider_domain stays and names the hostname the Worker fronts. build-lambda-edge.sh takes the publisher's hostname as a second argument.
  • Exchange. It applies one migration when it starts, 000052, which adds the table fora.subscription_records. No setting is removed and none becomes required. EXCHANGE_BOOT_FIXTURE_FILE is new and optional. EXCHANGE_BILLING_TB_ID_NAMESPACE is read only by the end-to-end build; a production build refuses to start when it is set.
  • Console. The edge package the console hands out no longer carries the discovery file. A publisher downloads fora.json and serves it from their own site.

Highlights

  • Subscription-gated terms. A licensing term that carries one concrete subscription: scope is sold only to an agent that proves the subscription with the holder-bound delegation chain in Requester.delegation. The chain must verify under the root keys of the subscription record that owns the scope, be bound to the key that signed the request, and cover the term. Any failure denies that item with DENIAL_REASON_DELEGATION_INVALID, with no transaction and no charge, and stating the scope in Requester.scopes grants nothing. At discovery, only a query the agent sends to the Exchange itself can see a gated term; a query a Broker sends for the agent does not show it. The Broker forwards Requester.delegation to every Exchange it asks, and a catalog push is refused for a term with two subscription scopes or a wildcard one. The records live in the new table fora.subscription_records. This release creates them only through the end-to-end build's control service and has no administrative route for them yet. The scope rule is in ADR-014.
  • The discovery file lives on the publisher's site. The edge passes /.well-known/fora.json and /rsl.txt through to the origin, so the file the publisher serves is the one every agent and Exchange reads. Editing it is how a publisher changes which Exchanges sell their pages and who may add pages to the catalogue. The console's check on Connect your site asks for the file the way an AI agent does: a site that refuses agents at that address is not verified, and the console says why. The demo and staging stacks serve each demo publisher's documents from its origin as well.
  • Publisher console onboarding. A new account goes through four steps: Your business, Your domain, Your terms and Connect your site. The business name is asked once, before the first domain, and cannot be left for later; every later domain takes only the three domain steps. The domain is saved on the first step's Next and the terms on the second step's Next. Finish later returns to My domains, and Finish setup reopens a domain on Your terms when no terms were chosen, and on Connect your site otherwise. Connect your site has two tasks, done in either order: serve your discovery file, and install the package on your CDN. The console checks both every 15 seconds and verifies the domain once both pass. An account with no domain sees an empty My domains with one Add domain button. The Cloudflare steps run npx wrangler login before npx wrangler deploy and say they need Node.js 22 or newer, and every price reads "per fetch". Design: ADR-026, amendments of 2026-10-28 and 2026-10-29.
  • Exchange boot fixture. EXCHANGE_BOOT_FIXTURE_FILE names a YAML file that declares the seats, publishers, sites and listings a deployment starts with. At every start the Exchange creates the declared rows that are not stored yet and changes nothing that is; a file it cannot read or apply stops the start. Design: ADR-029.
  • A lighter, stricter end-to-end suite. One TigerBeetle cluster serves every test Exchange, each with its own ledger-id namespace, one nginx serves every test key directory, and health checks poll quickly only while a service starts. The stack needs less than half the memory it did. Every test signs as an agent of its own, each Exchange starts from a boot fixture instead of database writes, and the harness builds its requests from the protocol's generated models and sends them through the SDKs in strict mode. ADR-028 is accepted. The real-AWS acceptance suite, which checked a CloudFront RSA path that no stack deploys, is retired.
  • Terraform. The CloudFront edge module's Lambda@Edge role allows logs:CreateLogGroup on the log-group ARN and the log-stream actions on the log-stream ARN, in two statements, as CloudWatch Logs requires.

Container images

Built from this tag for linux/amd64.

docker pull ghcr.io/fora-protocol/exchange:1.0.0
docker pull ghcr.io/fora-protocol/broker:1.0.0
docker pull ghcr.io/fora-protocol/identity:1.0.0
docker pull ghcr.io/fora-protocol/console:1.0.0
Image Digest
exchange sha256:ed8984992c4cc85269a34349f1235e488774d394eede0ea1df77b307eebb09f1
broker sha256:bd6a3cf96b8092267bac98229116a1b27f18f00de2714e6b648bdb9117306471
identity sha256:ee10ee1f5317485f34e0005a04bd965b68690f3a510b8faafbf515aa095b6580
console sha256:9fcd9a142fd43eb6ad797f0caa7d58cfa3a41ccfc64377856b10c50d3b0a2e76

Each service's DEPLOYMENT.md and CONFIGURATION.md say how to run it: exchange, broker, identity, console.

Protocol

Pinned to FORA protocol v1.2.0 everywhere: the Go module github.com/FORA-Protocol/protocol v1.2.0 for the services, @fora-protocol/sdk 1.2.0 for the edge, and fora-protocol-sdk 1.2.0 with the fora-protocol 1.2.0 models for the end-to-end tests.

Full Changelog: v1.0.0-rc.5...v1.0.0

v1.0.0-rc.5

v1.0.0-rc.5 Pre-release
Pre-release

Choose a tag to compare

@legendko legendko released this 20 Oct 13:00

v1.0.0-rc.5 moves the reference implementation onto FORA protocol v1.1.0, so every request it signs or verifies is a Web Bot Auth signature. It adds the publisher console, where publishers register their business and their sites, and the Exchange can now bill in more than one currency.

Upgrading from v1.0.0-rc.4

rc.5 does not interoperate with rc.4, and some rc.4 data does not carry over.

  • Protocol v1.1.0 (hard cut). rc.4 was built against an untagged protocol revision. v1.1.0 changes request signing in both directions, so the Exchange, the Broker, the Identity Service, every publisher edge and every agent upgrade together. Agent software built on the FORA SDKs needs v1.1.0.
  • Signed key directories. A v1.1.0 verifier takes a key only from a directory signed by that key. An edge that serves the publisher's own keys (WBA_KEYS_JSON) must also serve the pre-signed directory (WBA_SIGNED_DIRECTORY_JSON). Without it, the directory goes out unsigned.
  • Publisher sites are registered. The Exchange applies 18 database migrations when it starts (000034 to 000051). Migration 000036 removes signing_scheme and cloudfront_key_pair_id from the seat (fora.tenants) and does not copy them anywhere, because which publisher owns a site is decided at registration. Register each site again through the console after upgrading. The seat's domain now names the Exchange's own hostname.
  • Billing settings. EXCHANGE_BILLING_LEDGER takes a comma-separated list of ISO 4217 numeric codes, one ledger each (978 for EUR, 840 for USD). EXCHANGE_DEFAULT_AGENT_CREDIT takes CODE=AMOUNT pairs, such as EUR=100. The old single number stops the Exchange at boot.
  • Ledger balances do not carry over. Every TigerBeetle account id now includes its currency, so rc.5 does not find the accounts rc.4 created. Fund agents again after upgrading.
  • The console needs a PostgreSQL database of its own (CONSOLE_DSN) and two Exchange settings: EXCHANGE_CONSOLE_WELLKNOWN_URL and EXCHANGE_CATALOG_CONTRIBUTOR_HOST. Every other setting new to the existing services is optional, and none of their documented settings was removed.

Highlights

  • Web Bot Auth signing. The Identity Service, the Broker and the Exchange sign and verify every FORA request as Web Bot Auth. fora-sign-directory pre-signs a key directory for a host that serves it as a static file.
  • Publisher console (new service and image). Publishers sign in through a login provider separate from the one developers use. They register their business and sites, download the files to deploy, and confirm that each site is theirs. A dashboard shows an overview, transactions with in-browser verification, the catalog and income. Design: ADR-026.
  • Automatic catalog import. fora-import builds and refreshes each listing's catalog from the sitemap recorded at registration.
  • One signed offer per licensing term. Discovery returns one offer for each term the publisher offers, in the publisher's order, each with its own price and offer_id. Before, only the first term could be bought.
  • Several currencies. The Exchange keeps one TigerBeetle ledger per currency, and money never moves between them. Balances are reported per currency.
  • Refused purchases are recorded. The Exchange writes each refused purchase to an append-only journal. Design: ADR-027.
  • MCP tools. fora_discover accepts search_filters. fora_execute returns only the URLs when called with embed_content: false. fora_status reports one balance per currency.
  • Sign-in. Every authorization response carries the iss parameter (RFC 9207).
  • Operations. Each service takes its own log level: EXCHANGE_LOG_LEVEL, BROKER_LOG_LEVEL, IDENTITY_LOG_LEVEL and CONSOLE_LOG_LEVEL. A publisher edge can limit the paths it licenses with LICENSED_PATHS_JSON.
  • Testing. An obligation registry drives the end-to-end suite, and every protocol request in it goes through the protocol SDKs. Design: ADR-028. Each e2e run brings up its own stack on its own network, with no host ports, so runs never collide.
  • Demo content. Playable music tracks offered under alternative licences (the fora-music-v1 profile), plus new essays and articles.

Container images

Built from this tag for linux/amd64. The console image is new in this release.

docker pull ghcr.io/fora-protocol/exchange:1.0.0-rc.5
docker pull ghcr.io/fora-protocol/broker:1.0.0-rc.5
docker pull ghcr.io/fora-protocol/identity:1.0.0-rc.5
docker pull ghcr.io/fora-protocol/console:1.0.0-rc.5
Image Digest
exchange sha256:362b9c1b1b7392687bb6eb94ea0a4e398e203c4bdc14cf677536ac3e9838e78d
broker sha256:2cb6a282b37eee1faa077a67a319d0fb1514de4d9723806af9bd3203c170ded2
identity sha256:de5f5fdc70a0d5dc254440337c660f159bbc3d47eda1bc92606854bb157dbc58
console sha256:55fcba0fb8efbcb80727cde444323eb66a369cae9392723dc5d0a8622bb1cec6

Each service's DEPLOYMENT.md and CONFIGURATION.md say how to run it: exchange, broker, identity, console.

Protocol

Pinned to FORA protocol v1.1.0 everywhere: the Go module github.com/FORA-Protocol/protocol v1.1.0 for the services, @fora-protocol/sdk 1.1.0 for the edge, and fora-protocol-sdk 1.1.0 for the end-to-end tests.

Full Changelog: v1.0.0-rc.4...v1.0.0-rc.5