Repository navigation
v1.2.1
Release Notes v1.2.1
Released: 2026-08-13
A security and correctness patch on top of 1.2.0. Four fixes land here: scope enforcement on the MCP surface, org scoping on the backup job status route, fail-fast production deploys without a real JWT signing key, and removal of benchmark corpus vocabulary from the production retrieval ranker. The release also publishes the 2026-08-13 architecture audit that motivated the retrieval work.
Highlights
MCP tools now honor api:read / api:write
REST refused mutating calls for a key scoped ["api:read"], but that gate only fires on paths under /api/ and MCP mounts at /. Nothing downstream read scopes, so the same key could drive add, remember, reflect, manage, and synthesis_draft. The scope vocabulary now lives in apps/api/src/sibyl/auth/mcp_auth.py and both surfaces read it: mcp admits a credential to the surface, api:read and api:write refine what it may do there. Enforcement sits on _require_mcp_context(write=...) in server.py, which every tool already calls, so the flag travels with the helper instead of each tool body.
Backup job status is scoped to the caller's organization
GET /backups/jobs/{job_id} took only job_id and performed no visibility check, so any authenticated caller could read any org's job envelope. The handler now resolves the caller's org through get_current_organization and reuses the jobs router's visibility check.
Production refuses to start with a weak signing key
A stock helm install charts/sibyl shipped a production-labelled deploy with MCP auth disabled: the default SIBYL_ENVIRONMENT is production while backend.existingSecret is empty, so the SIBYL_JWT_SECRET block was skipped and the server ran with an empty key. Both layers now fail fast. The new sibyl.validateProductionAuthSecret helper aborts the render, and validate_production_auth_posture in apps/api/src/sibyl/config.py aborts the boot.
The production ranker no longer scores queries against LongMemEval vocabulary
The coverage ranker matched every user query against tables built from benchmark scenario content: _CONCEPT_GROUPS held seattle, basil, airfryer, powerbank, triathlon, and the dataset misspelling buisiness; _CATEGORY_ALIASES mapped kitchen and haircare queries onto product nouns. Those tables fed _query_frame_score at weight 0.52, the largest term in the model after rank itself. Every table that enumerates topic vocabulary is gone, along with _concept_overlap_score and its three weights.
1.3 rethink and seven-lane audit published
docs/architecture/SIBYL_1_3_RETHINK_2026-08-13.md plus seven reports under docs/architecture/AUDIT_2026-08-13/ (four tech-debt deep dives, an expressiveness map, two SOTA sweeps). docs/.vitepress/config.mts gains architecture/AUDIT_*/** to srcExclude so audit bundles never publish.
API and Auth
- Scopeless keys no longer walk in.
load_access_tokenused to upgrade a key with zero scopes to["mcp"]before checking it, which also masked the check directly below. Empty stored scopes are now resolved explicitly byeffective_api_key_scopes, so keys predating the scopes column (migration0b6b47ef,server_default '{}'with no backfill) keep working while the masking stays fixed. - The unrestricted carve-out is the bare shape only. A key holding
mcpalongside any unrecognized scope previously read as bare-mcpand kept full write access. Any further claim on a key now means its capabilities were enumerated, so a write has to be enumerated too. - Issuance refuses an empty scope list.
create_api_key_for_userinpersistence/surreal/auth_runtime/api_keys.pyraisesValueErrorfor[],[""], or[" "]before it opens a client, so the legacy read-path carve-out covers only rows already in the store. sibyl://healthclears the read gate. The one MCP entry point that resolved its org outside the gate now routes through_optional_mcp_org_id. It stays anonymous-friendly, but a credential that is presented is refused rather than silently downgraded to anonymous.- Job-existence oracle closed. Before this change
GET /backups/jobs/{job_id}answered200in both directions: the full envelope for another org's job, and a200carrying anot_foundbody for an id the queue never held. Both now answer an identical404, so the route cannot be used to probe for foreign job ids. Thejobs.pychange is only the rename of_job_visible_to_orgtojob_visible_to_orgsobackups.pycan import it; no route in that file changed behavior. run_backupgains an org argument index incoordination/broker.py, which is what lets the visibility check resolve a backup job's owning org.
Deployment Safety
validate_production_auth_posturerejects an empty signing key, a key with leading or trailing whitespace (the trailing newline from$(cat secret.txt)or a file-projected Secret), a key shorter than 32 bytes, andmcp_auth_mode=off. It runs aftercheck_api_key_fallbacksso the unprefixedJWT_SECRETfallback is applied first. Whitespace is rejected rather than trimmed, because trimming would change the signature and split a rolling upgrade.- The chart guard is included from
configmap.yaml, which always renders. It rejects production with nobackend.existingSecret, an inlinebackend.env.SIBYL_JWT_SECRETorbackend.env.JWT_SECRETin any casing (everybackend.envkey is written verbatim into the plaintext<release>-configConfigMap), andSIBYL_MCP_AUTH_MODE=off. - Remediation text threads
.Release.Namespaceand.Release.Namethroughprintf, recommendshelm upgrade --reuse-valuesfor an existing release, and validates interpolated names against an RFC 1123 pattern so an operator-supplied value cannot smuggle a shell substitution into a snippet meant for pasting. - The chart deliberately does not auto-generate the secret in production: a per-render value would rotate on every upgrade and diverge across the backend, worker, and bootstrap pods.
helm lintstays green on helm 3.20.2 and 4.2.3, since a templatefailis reported at INFO level. - The Redis-profile worker in
docker-compose.prod.ymlnow receives the API'sSIBYL_JWT_SECRET. It was labelled production with no key, so the new validator raised at import and only the worker crash-looped. SIBYL_HELM_RENDER_ARGSintools/trust/enterprise_readiness_evidence.pysetsbackend.existingSecret, sorendered_helm_manifestscertifies a correctly secured manifest instead of hitting the guard. CI production jobs in.github/workflows/ci.ymluse a signing key long enough to clear the 32-byte floor.
Retrieval
query_ranking.pyloses about 440 lines (+30 / -467), taking the file from 2016 to 1579 lines, roughly 20% smaller. What survives is machinery that reads as ordinary English: action-verb synonym groups, the assistant-artifact frame, the brand-lookup frame, and the how-often frequency frame with its doctor-specific alternates stripped._CATEGORY_TERMSis removed fromretrieval/fact_frames.pyalong with the labels only reachable through it (appliance,event,tool,life_event). Category labels that linguistic evidence can produce still work through_SERVICE_USE_PATTERNand_PROFILE_PATTERN. The cost is stated plainly: a query phrased with a bare category noun ("what audio app have I been using") no longer classifies.- Suppression lists were costing recall too.
_PREFERENCE_QUERY_SCAFFOLDING_TERMSdroppedserve,watch,weekend, andvisit, which are scaffolding in a recommendation request and the subject everywhere else.freeleft the keyword stopword list because it carries meaning in free software, free tier, and free trial;test_query_coverage_keeps_free_as_contentpins that the token survives keyword extraction. - Comparative normalization, minus the homographs. A closed 49-entry table maps comparative and superlative adjectives onto their base form, restoring what the concept-group removal took with it (
olderandoldare the same lemma). Five noun and verb homographs are excluded from the comparative direction:test_query_coverage_ranks_a_lighter_above_a_lightpins that "Which lighter did I buy?" ranks a Zippo above a garage light rather than normalizing tolight. Superlatives still normalize, since nothing readslightestas a noun. presentandvolunteerare split into separate single-member groups on both the_action_evidence_scoreand fact-frame paths. They cohere only as things a person does at an event, which is the shape of the benchmark's aggregate-event question rather than a fact about English.- The hardcoded
buisinesscorrection leavesnormalize_keyword_token,airfryerandsmokerleave the fact-frame appliance terms, and the corpus examples leave thememory_extraction.pyprompt. Stem-alias tables stay, minus three plurals the generic fallback already normalizes identically.
Tests
apps/api/tests/test_route_auth_coverage.pyreads the mounted app rather than calling it, so a route that never declared its auth dependencies stops looking like one that did. It credits only parameter-bound dependencies, because aDepends()in a decorator can prove a check ran but can never hand the handler an organization.apps/api/tests/test_mcp_scope_enforcement.pyandtest_mcp_entry_point_scope_coverage.pyinvoke every entry point the FastMCP managers hold (tools, resources, resource templates, prompts) under three credentials: nomcpscope, read-only, andapi:write. Store boundaries are swapped for recorders, so "nothing was written before the refusal" is observed rather than inferred. Walking the managers means an ungated template or prompt is covered on the turn it is registered.- Retrieval tests are mutation-verified: deleting the frequency frame branch from
_query_frame_scorenow fails both of its tests, where it used to fail neither, and puttinglighterback in the comparative table fails the homograph tests.
CLI
sibyl db backup-create --waitdistinguishes the API's ownnot_foundenvelope from any 404 (a reverse proxy, a stale route table, or an older server), so an unreachable API is no longer read as "the record is gone". The command also handles a cancelled job and exits1unless it confirmed a successful archive, since--waitpromises the archive exists by the time it returns.
Breaking Changes
- Production boots are validated. A production process is refused if its JWT secret is empty, padded with whitespace, shorter than 32 bytes, or if
SIBYL_MCP_AUTH_MODE=off. Generate a replacement withopenssl rand -hex 32. - Production Helm renders fail without a Secret.
helm templateandhelm installabort unlessbackend.existingSecretis set. An inlinebackend.env.SIBYL_JWT_SECRETorbackend.env.JWT_SECRETis rejected in production regardless of casing. - API keys with granular scopes are restricted on MCP. A key carrying
api:readalongsidemcpcan no longer invokeremember,reflect,add,manage, orsynthesis_draftwithremember=true. Keys whose only scope ismcp, and keys stored with an empty scope list, keep unrestricted MCP access. create_api_key_for_userraises on an empty scope list. Direct callers passing[],[""], or[" "]now get aValueErrorinstead of a key with legacy MCP access.GET /backups/jobs/{job_id}requires org context and answers404for unknown and foreign job ids alike.- Retrieval results move. This deliberately changes ranking behavior. A fresh LongMemEval anchor run is the planned next step.
Upgrade Notes
- Before upgrading a production Helm release, create the Secret in the release namespace and set
backend.existingSecret. Usehelm upgrade --reuse-valuesor re-apply your values files, since--setalone resets a release to chart defaults. - Check that your signing key is at least 32 bytes and carries no trailing newline. A file-projected Kubernetes Secret is the usual source of the newline.
- If you run the Redis-profile worker from
docker-compose.prod.yml, give it the sameSIBYL_JWT_SECRETas the API. Divergent keys make the two processes disagree on signatures. - Audit API keys used by agents over MCP. Any key with granular REST scopes needs
api:writefor mutating tools; add it before upgrading, or the tools start refusing. - Image tags, chart versions, and the pinned
sibyl-coredependency move to1.2.1. UpdateSIBYL_IMAGE_TAGandsibyl docker upgrade --tag 1.2.1accordingly. - Re-run your retrieval evaluations. Ranking is intentionally different from 1.2.0.