Skip to content

v1.2.1

Choose a tag to compare

@github-actions github-actions released this 13 Aug 22:47
· 431 commits to main since this release
e354ab7

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_token used 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 by effective_api_key_scopes, so keys predating the scopes column (migration 0b6b47ef, server_default '{}' with no backfill) keep working while the masking stays fixed.
  • The unrestricted carve-out is the bare shape only. A key holding mcp alongside any unrecognized scope previously read as bare-mcp and 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_user in persistence/surreal/auth_runtime/api_keys.py raises ValueError for [], [""], or [" "] before it opens a client, so the legacy read-path carve-out covers only rows already in the store.
  • sibyl://health clears 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} answered 200 in both directions: the full envelope for another org's job, and a 200 carrying a not_found body for an id the queue never held. Both now answer an identical 404, so the route cannot be used to probe for foreign job ids. The jobs.py change is only the rename of _job_visible_to_org to job_visible_to_org so backups.py can import it; no route in that file changed behavior.
  • run_backup gains an org argument index in coordination/broker.py, which is what lets the visibility check resolve a backup job's owning org.

Deployment Safety

  • validate_production_auth_posture rejects 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, and mcp_auth_mode=off. It runs after check_api_key_fallbacks so the unprefixed JWT_SECRET fallback 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 no backend.existingSecret, an inline backend.env.SIBYL_JWT_SECRET or backend.env.JWT_SECRET in any casing (every backend.env key is written verbatim into the plaintext <release>-config ConfigMap), and SIBYL_MCP_AUTH_MODE=off.
  • Remediation text threads .Release.Namespace and .Release.Name through printf, recommends helm upgrade --reuse-values for 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 lint stays green on helm 3.20.2 and 4.2.3, since a template fail is reported at INFO level.
  • The Redis-profile worker in docker-compose.prod.yml now receives the API's SIBYL_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_ARGS in tools/trust/enterprise_readiness_evidence.py sets backend.existingSecret, so rendered_helm_manifests certifies a correctly secured manifest instead of hitting the guard. CI production jobs in .github/workflows/ci.yml use a signing key long enough to clear the 32-byte floor.

Retrieval

  • query_ranking.py loses 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_TERMS is removed from retrieval/fact_frames.py along with the labels only reachable through it (appliance, event, tool, life_event). Category labels that linguistic evidence can produce still work through _SERVICE_USE_PATTERN and _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_TERMS dropped serve, watch, weekend, and visit, which are scaffolding in a recommendation request and the subject everywhere else. free left the keyword stopword list because it carries meaning in free software, free tier, and free trial; test_query_coverage_keeps_free_as_content pins 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 (older and old are the same lemma). Five noun and verb homographs are excluded from the comparative direction: test_query_coverage_ranks_a_lighter_above_a_light pins that "Which lighter did I buy?" ranks a Zippo above a garage light rather than normalizing to light. Superlatives still normalize, since nothing reads lightest as a noun.
  • present and volunteer are split into separate single-member groups on both the _action_evidence_score and 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 buisiness correction leaves normalize_keyword_token, airfryer and smoker leave the fact-frame appliance terms, and the corpus examples leave the memory_extraction.py prompt. Stem-alias tables stay, minus three plurals the generic fallback already normalizes identically.

Tests

  • apps/api/tests/test_route_auth_coverage.py reads 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 a Depends() in a decorator can prove a check ran but can never hand the handler an organization.
  • apps/api/tests/test_mcp_scope_enforcement.py and test_mcp_entry_point_scope_coverage.py invoke every entry point the FastMCP managers hold (tools, resources, resource templates, prompts) under three credentials: no mcp scope, read-only, and api: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_score now fails both of its tests, where it used to fail neither, and putting lighter back in the comparative table fails the homograph tests.

CLI

  • sibyl db backup-create --wait distinguishes the API's own not_found envelope 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 exits 1 unless it confirmed a successful archive, since --wait promises 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 with openssl rand -hex 32.
  • Production Helm renders fail without a Secret. helm template and helm install abort unless backend.existingSecret is set. An inline backend.env.SIBYL_JWT_SECRET or backend.env.JWT_SECRET is rejected in production regardless of casing.
  • API keys with granular scopes are restricted on MCP. A key carrying api:read alongside mcp can no longer invoke remember, reflect, add, manage, or synthesis_draft with remember=true. Keys whose only scope is mcp, and keys stored with an empty scope list, keep unrestricted MCP access.
  • create_api_key_for_user raises on an empty scope list. Direct callers passing [], [""], or [" "] now get a ValueError instead of a key with legacy MCP access.
  • GET /backups/jobs/{job_id} requires org context and answers 404 for 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. Use helm upgrade --reuse-values or re-apply your values files, since --set alone 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 same SIBYL_JWT_SECRET as 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:write for mutating tools; add it before upgrading, or the tools start refusing.
  • Image tags, chart versions, and the pinned sibyl-core dependency move to 1.2.1. Update SIBYL_IMAGE_TAG and sibyl docker upgrade --tag 1.2.1 accordingly.
  • Re-run your retrieval evaluations. Ranking is intentionally different from 1.2.0.