Repository navigation
Releases
v1.1.0
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_DISCOVERYis replaced byBROKER_QUERY_PROVIDER. If your Broker ran query discovery withBROKER_QUERY_DISCOVERY=on, setBROKER_QUERY_PROVIDER=llminstead.BROKER_QUERY_CATALOG_FILE,BROKER_QUERY_MODELandBROKER_QUERY_URI_SCHEMEkeep their meaning. The old setting is no longer read: a Broker that still sets onlyBROKER_QUERY_DISCOVERYstarts with no catalog search and logsbroker.query_discovery.disabled.BROKER_QUERY_PROVIDER=onstops the Broker at start-up. If you deploy with the Terraformcompose-stackmodule or the demo and staging stacks, nothing changes for you:query_discoveryworks as before. - Identity.
IDENTITY_MCP_SEARCH_FILTERS_SCHEMA(or its_FILEform) is new and optional. Leave it unset unless the Broker behind this service runs theelasticsearchprovider. Unset,fora_discoverchecks no filter itself and passessearch_filtersto the Broker, as in v1.0.0. - Console. No setting is new or removed.
CONSOLE_SUPPORT_EMAILis now also written into the README of every edge package, so set it. - Terraform. The
compose-stackmodule and thedemo-awsandstaging-awsstacks take a new optionalelasticsearch_searchobject. No variable is removed. Theaws-vmmodule has a new output,data_volume_name.
Highlights
- Catalog search providers.
BROKER_QUERY_PROVIDERselects 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) orelasticsearch. 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,filtersandlimit. 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/templateand_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 isapi_key,basicornone, with no default. Plainhttpneeds its own opt-in (BROKER_ES_ALLOW_HTTP), and bothnoneand plainhttplog 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 issrc/broker/SEARCH-TEMPLATE.md, and a working template and filter schema to start from are indeploy/broker/. Design: ADR-030. - Declared search filters. A deployment declares the
search_filterskeys its template applies, and the format of each value, in a JSON Schema (BROKER_ES_FILTERS_SCHEMAorBROKER_ES_FILTERS_SCHEMA_FILE). The Broker checks every request against it before it searches: a key the schema does not declare is refused withUNIMPLEMENTED, and a value it refuses withINVALID_ARGUMENT, each naming the fieldsearch_filters.<key>. A filter is never dropped, and with no schema every filter is refused. The Identity service'sfora_discovertool shows the same schema to agents as the input schema ofsearch_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_EMAILis set, where to write for help. - Terraform. With
elasticsearch_searchset, thecompose-stackmodule and the demo and staging stacks run the Broker on theelasticsearchprovider. The module takes anhttpsURL 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
elasticsearchprovider, 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
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, andDelegation.tokenis at most 32768 bytes. Move agents and other clients to the v1.2.0 SDKs. - The edge no longer answers
/.well-known/fora.jsonor/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 (thefora.jsonthe publisher console gives you), and the RSL file if you have one. The edge no longer readsPROVIDER,EXCHANGES_JSON,CATALOG_CONTRIBUTORS_JSONorRSL_BODY: a deployment that still sets them starts and ignores them. The domain-verification route/.well-known/fora-verify/<token>and its settingACME_TOKENS_JSONare removed. - Terraform. The
cloudflare-edgemodule no longer takesprovider_domain,exchanges_json,rsl_body,acme_tokens_jsonorcatalog_contributors_json: remove them from the module block. Theedgestack drops the last four; itsprovider_domainstays and names the hostname the Worker fronts.build-lambda-edge.shtakes the publisher's hostname as a second argument. - Exchange. It applies one migration when it starts,
000052, which adds the tablefora.subscription_records. No setting is removed and none becomes required.EXCHANGE_BOOT_FIXTURE_FILEis new and optional.EXCHANGE_BILLING_TB_ID_NAMESPACEis 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.jsonand 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 inRequester.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 withDENIAL_REASON_DELEGATION_INVALID, with no transaction and no charge, and stating the scope inRequester.scopesgrants 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 forwardsRequester.delegationto 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 tablefora.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.jsonand/rsl.txtthrough 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 loginbeforenpx wrangler deployand 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_FILEnames 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:CreateLogGroupon 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 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 (
000034to000051). Migration000036removessigning_schemeandcloudfront_key_pair_idfrom 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'sdomainnow names the Exchange's own hostname. - Billing settings.
EXCHANGE_BILLING_LEDGERtakes a comma-separated list of ISO 4217 numeric codes, one ledger each (978for EUR,840for USD).EXCHANGE_DEFAULT_AGENT_CREDITtakesCODE=AMOUNTpairs, such asEUR=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_URLandEXCHANGE_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-directorypre-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-importbuilds 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_discoveracceptssearch_filters.fora_executereturns only the URLs when called withembed_content: false.fora_statusreports one balance per currency. - Sign-in. Every authorization response carries the
issparameter (RFC 9207). - Operations. Each service takes its own log level:
EXCHANGE_LOG_LEVEL,BROKER_LOG_LEVEL,IDENTITY_LOG_LEVELandCONSOLE_LOG_LEVEL. A publisher edge can limit the paths it licenses withLICENSED_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-v1profile), 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