Fastify TypeScript baseline for the OSHUN backend-for-frontend.
Routes#
GET /healthzliveness probeGET /readyzreadiness probe with normalized per-domain degradation summaryGET /homehome aggregator feed (highlights + continue strip)GET /v1/homecompatibility alias forGET /homeGET /continueresumable cross-domain items feedGET /v1/continuecompatibility alias forGET /continueGET /libraryunified saved/favorites library feedGET /v1/librarycompatibility alias forGET /libraryGET /domainsdomain catalog with metadata, availability, scope flags, and entitlement access evaluationsGET /v1/domainscompatibility alias forGET /domainsGET /activityunified cross-domain activity timeline feedGET /v1/activitycompatibility alias forGET /activityGET /searchunified cross-domain search feedGET /v1/searchcompatibility alias forGET /searchGET /search/suggestionsquery suggestions + recent searches feedGET /v1/search/suggestionscompatibility alias forGET /search/suggestionsGET /notificationsunified notifications feedGET /v1/notificationscompatibility alias forGET /notificationsPOST /notifications/:notificationId/readmark a notification as readPOST /notifications/read/bulkbulk mark notifications as readPOST /v1/notifications/:notificationId/readcompatibility aliasPOST /v1/notifications/read/bulkcompatibility aliasGET /notifications/preferencesread per-domain notification preferencesPATCH /notifications/preferences/domains/:domainIdupdate per-domain notification preferencesGET /v1/notifications/preferencescompatibility aliasPATCH /v1/notifications/preferences/domains/:domainIdcompatibility aliasGET /profileauthenticated shell profile envelopeGET /v1/profilecompatibility alias forGET /profilePATCH /profileupdate shell profile fields (displayName,email)PATCH /v1/profilecompatibility alias forPATCH /profileGET /preferencesauthenticated shell preferences envelopeGET /v1/preferencescompatibility alias forGET /preferencesPATCH /preferencesupdate shell preferences (theme,language, notification toggles)PATCH /v1/preferencescompatibility alias forPATCH /preferencesGET /nisaba/passages/dailyauthenticated Nisaba daily passage envelopeGET /v1/nisaba/passages/dailycompatibility alias forGET /nisaba/passages/dailyGET /nisaba/passages/:passageIdNisaba passage detail envelopeGET /v1/nisaba/passages/:passageIdcompatibility aliasGET /nisaba/passages/:passageId/annotationslist passage annotationsGET /v1/nisaba/passages/:passageId/annotationscompatibility aliasPOST /nisaba/passages/:passageId/annotationscreate passage annotationPOST /v1/nisaba/passages/:passageId/annotationscompatibility aliasPATCH /nisaba/passages/:passageId/annotations/:annotationIdupdate passage annotationPATCH /v1/nisaba/passages/:passageId/annotations/:annotationIdcompatibility aliasGET /nisaba/passages/:passageId/compareNisaba compare workspace envelopeGET /v1/nisaba/passages/:passageId/comparecompatibility aliasGET /nisaba/notebookslist Nisaba notebooksGET /v1/nisaba/notebookscompatibility alias forGET /nisaba/notebooksPOST /nisaba/notebookscreate Nisaba notebookPOST /v1/nisaba/notebookscompatibility alias forPOST /nisaba/notebooksGET /nisaba/notebooks/:notebookIdNisaba notebook detail envelopeGET /v1/nisaba/notebooks/:notebookIdcompatibility aliasPATCH /nisaba/notebooks/:notebookIdupdate Nisaba notebook metadataPATCH /v1/nisaba/notebooks/:notebookIdcompatibility aliasPOST /nisaba/notebooks/:notebookId/itemsadd a passage, annotation, grounded evidence view, or compare workspace to a notebookPOST /v1/nisaba/notebooks/:notebookId/itemscompatibility aliasGET /nisaba/passages/:passageId/grounded-evidencegrounded evidence view envelopeGET /v1/nisaba/passages/:passageId/grounded-evidencecompatibility aliasGET /admin/workspacesadmin workspace summary feedGET /v1/admin/workspacescompatibility alias forGET /admin/workspacesGET /admin/workspaces/:workspaceIdadmin workspace detail envelope forreview | moderation | support | privacy | persona | model | rights | incident | policy | analyticsGET /v1/admin/workspaces/:workspaceIdcompatibility aliasPOST /admin/review/items/:reviewId/assignassign a review itemPOST /admin/review/items/:reviewId/decisionrecord a review decisionPOST /admin/moderation/queues/:queueId/simulationscreate a moderation policy simulationPOST /admin/support/cases/:caseId/escalateescalate a support casePOST /admin/privacy/requests/:requestId/resolveresolve a privacy requestPOST /admin/personas/:personaId/publishpublish a persona versionPOST /admin/models/:modelId/promotepromote a model to staging or productionPOST /admin/rights/requests/:requestId/resolveresolve a rights requestPOST /admin/incidents/:incidentId/mitigatemove an incident into monitoringPOST /admin/policies/:policyId/publishpublish a policy revisionPOST /admin/analytics/reportsgenerate an analytics report snapshotPOST /v1/admin/...compatibility aliases are available for each admin mutation route aboveGET /v1/entitlements/domains/:domainIdevaluates domain access by entitlement contextGET /v1/domains/:domainId/bootstrapprotected domain bootstrap route (entitlement middleware)GET /api/v6/catalogV6 Egbe catalog, client tiers, world modes, and contract registryPOST /api/v6/tier-router/routeV6 native / Pixel Streaming / web fallback tier routingGET /api/v6/steward/appEgbe Steward App bootstrap envelopePOST /api/v6/steward/objectivescreate or replace a remote steward objective using the canonical V6ObjectivecontractPOST /api/v6/steward/crossroads/:crossroadsId/counselrecord steward counsel for a V6CrossroadscontractGET /api/v6/homesteadaccount-bound homestead statePATCH /api/v6/homestead/settingsupdate homestead rest pace and world-mode settingsPOST /api/v6/homestead/visit-invitescreate a co-op homestead visit inviteGET /api/v6/account/bridgeread the V1 account to V6 steward bridgePATCH /api/v6/account/preferencesupdate V6 bridge preferences
Feed Pagination, Cache, and Partial-Failure Behavior#
- Feed routes support cursor pagination:
GET /home:highlightsLimit,highlightsCursor,continueLimit,continueCursor,favoritesLimit,favoritesCursorGET /continue,GET /domains,GET /activity,GET /search,GET /library,GET /notifications,GET /search/suggestions:limit,cursor
GET /librarysupportsdomain=all|tara|veritas|nyx|arete|nisaba|metis- Notifications filters:
inbox=all|unread|priority,domain=all|tara|veritas|nyx|arete|nisaba - Notifications feeds are filtered by per-domain preference state (
enabled,priorityOnly, andkindstoggles). - Notifications feeds deduplicate semantic cross-domain duplicates (same normalized title/body in a shared time window) and keep the highest-signal candidate.
- Responses include pagination envelopes, a
partialFailureboolean, and atraceenvelope with the current request correlation ID, route, normalized failure count, degraded domains, and degraded stages. - Partial-response aware routes also emit:
x-oshun-partial-response: true|falsex-oshun-partial-failure-count: <n>x-oshun-degraded-domains: tara,veritas,...when degradation is presentx-oshun-degraded-stages: continue,highlight,...when stage-aware degradation is present
- Feed routes apply short-lived private response caching with
x-oshun-cache: hit|missandcache-controlheaders. - Profile and preferences routes return revisioned envelopes that can be cached client-side and patched incrementally.
- Nisaba passage, annotations, compare, notebook, and grounded-evidence reads also emit revisioned envelopes with short-lived private cache headers.
- Nisaba compare target launch metadata now resolves directly to compare workspaces instead of target passage detail pages.
- Nisaba annotation and notebook mutations validate linked passage, notebook, and grounded-evidence references before mutating per-user state.
Search Ranking Strategy#
- Search ranking uses a weighted lexical + intent + kind model.
- Reference:
docs/releases/v1/specs/search-ranking-strategy.md
Search Telemetry#
- BFF emits typed analytics events for search:
search_executedsearch_zero_results(only when query is non-empty and no matches)
- Telemetry is emitted for both
/searchand/search/suggestionsresponses.
Domain API Adapters#
- Typed adapter factory:
src/adapters/domain-service-adapters.ts - Includes strongly-typed clients for Tara, Veritas, Nyx, and Arete.
- Adapter contract covers health checks plus typed home/continue primitives for aggregator endpoints.
getHealth()normalizes heterogeneous upstream health/readiness payloads into one shell-facing model:ok | degraded | down.- Active adapters now probe domain-specific readiness or liveness paths instead
of assuming one shared
/healthzendpoint.
Domain Health and Readiness#
- BFF liveness remains
GET /healthz. - BFF readiness returns
status: ready | degraded | not_readyplus:ready: whether the shell should remain in rotationdomains: normalized Tara/Veritas/Nyx/Arete health statusessummary: per-status counts plus impacted/down domain lists
- Active probe paths:
- Tara:
/ready - Veritas:
/readyz - Nyx:
/health - Arete:
/v1/arete/healthz
- Tara:
- Health probes follow a shared retry and circuit-breaker policy:
- timeout
2000ms 1retry for retryable probe failures- circuit breaker threshold
5 - circuit reset timeout
30000ms - half-open max
3
- timeout
Domain Service Discovery#
- Active adapter upstreams are configured through:
OSHUN_TARA_API_BASE_URLOSHUN_VERITAS_API_BASE_URLOSHUN_NYX_API_BASE_URLOSHUN_ARETE_API_BASE_URL
- Residency data-plane overrides use the same variables with an uppercase zone
suffix, for example
OSHUN_TARA_API_BASE_URL_EU,OSHUN_VERITAS_API_BASE_URL_US, orOSHUN_ARETE_API_BASE_URL_APAC. When an authenticated request carries ahomeZoneclaim, the BFF routes downstream domain calls to the user's home zone. A request only routes to a differentX-Oshun-Residency-Target-Zonewhen the customer has an active explicitdata_processingconsent grant. - The older
TARA_API_URL,VERITAS_API_URL,NYX_API_URL, andARETE_API_URLnames are still accepted as compatibility aliases, but new environments should use theOSHUN_*variables. - In
developmentandtest, the BFF falls back to canonical local adapter ports:- Tara
http://localhost:4101 - Veritas
http://localhost:4201 - Nyx
http://localhost:4301 - Arete
http://localhost:4401
- Tara
- In
stagingandproduction, the BFF fails fast unless each upstream origin is set explicitly. UseOSHUN_RUNTIME_ENV=staging|productionto enable non-development routing policy. OSHUN_DEPLOYMENT_RESIDENCY_ZONEsets the deployment's default target zone. It defaults to the canonical residency policy home zone (us).
OpenAPI#
- Source spec:
openapi/oshun-bff.openapi.yaml - Consumer contract notes:
../web/docs/bff-api-contract.md - Admin contract notes:
../web/docs/admin-bff-api-contract.md
Integration Coverage#
pnpm test:integrationruns the BFF-local integration harness invitest.integration.config.ts.src/__tests__/shell-domain-connectivity.integration.test.tsvalidates end-to-end HTTP connectivity from shell requests into the BFF and out through the live Tara, Veritas, Nyx, and Arete adapters for readiness, home, and continue flows.
Entitlement Headers#
x-oshun-tier:free | pro | premiumx-oshun-suspended-domains: comma-separated domain ids (for temporary suspensions)x-oshun-domain-tier-overrides: comma-separateddomain:tieroverrides (for support/testing)
Device Integrity Headers (High-Risk Routes)#
x-oshun-device-platform:ios | android | webx-oshun-device-integrity:verified | browser_verifiedx-oshun-device-attested-at: ISO-8601 attestation timestamp (must be fresh)
Abuse Protection#
- Entitlement and bootstrap routes apply in-memory rate limiting to reduce brute-force abuse.
- Exceeded limits return
429 Too Many Requestswithretry-afterheader.
Request Tracing#
- All routes support correlation propagation via
x-correlation-id. - If absent, BFF issues a request-scoped correlation id and returns it in the response header.
- Completion logs include correlation id, route, status code, and duration.
Auth and Domain Authorization#
- Protected domain routes require
Authorization: Bearer <token>. - Local/test development token format:
dev.<base64url-json-payload>.- Payload shape:
{ "sub": "user-id", "scopes": ["domain:*" | "domain:tara" | ...], "exp": <unix-seconds> }
- Payload shape:
- Production (
NODE_ENV=production,OSHUN_ENV=production, orRUNTIME_ENV=production) rejects unsigneddev.tokens. SetOSHUN_BFF_JWT_SECRETto a 32+ character HMAC secret and issue signed HS256 JWTs with issuerOSHUN_BFF_JWT_ISSUER(defaultoshun-auth) and audienceOSHUN_BFF_JWT_AUDIENCE(defaultoshun-bff). - Domain-scoped authorization requires either
domain:*ordomain:{domainId}scope. - Admin workspace routes require one of:
admin:*admin:studioadmin:workspace:{workspaceId}
- Home aggregation requires at least one domain scope and only queries authorized domains.
- Nisaba reader routes specifically require
domain:*ordomain:nisaba.
Signup verification deployment settings#
OSHUN_SIGNUP_VERIFICATION_HMAC_SECRETis required when the durable admin snapshot database is configured. It must contain at least 32 bytes and must remain stable across deploys; the BFF fails startup if it is missing or does not match the stored snapshot.OSHUN_SIGNUP_EMAIL_DELIVERY_URLselects the transactional-mail relay;OSHUN_SIGNUP_EMAIL_DELIVERY_TOKENis its optional bearer token. The relay must honor the suppliedIdempotency-Key/requestIdand return a stablemessageIdfor retries.OSHUN_SIGNUP_CHALLENGE_PROVIDERandOSHUN_SIGNUP_CHALLENGE_SITE_KEYbind the challenge provider. Missing challenge configuration fails the escalation tier closed.- Verification evidence is retained for at most 24 hours, resend timestamps for one hour, and velocity observations for 24 hours. Raw codes, network prefixes, and device fingerprints are never written to the snapshot.
Commands#
pnpm nx run @oshun/bff:devpnpm nx run @oshun/bff:buildpnpm nx run @oshun/bff:startpnpm nx run @oshun/bff:lintpnpm nx run @oshun/bff:typecheckpnpm nx run @oshun/bff:test