Connected apps with 3rd-party data hosts jsr.io/@civility
civility docs hosting features services.md
11 kB · 193 lines
Markdown
at main

CivServices setup #

CivServices lets apps call external services (including AI models, podcast search, and RSS fetching) in three modes: client-direct (browser → provider with the user's own key), server-proxy (through your server with the user's stored key), and bundle (through your server with a host-owned key, metered against the user's tier). This page is how an operator turns each part on; the design is in services spec §11.3–§11.4.


Default state: dormant #

Out of the box CivServices does nothing outbound. The CLI registers the standard AI and podcast services, but leaves proxying off. Custom servers must register their desired definitions, so:

  • the public catalog (GET /services) and encryption pubkey (GET /services/pubkey) are served — the namespace is reserved — but
  • proxyEnabled is false, so the server makes no outbound calls on a user's behalf, and
  • there are no bundle credentials, so only client-direct services are usable.

Operators can enable server-proxy and bundle calls in /admin/services → Allow service proxying. This switch is stored in the database and takes effect without a restart; disabling it blocks both modes, even when a bundle credential exists. It does not affect browser-direct calls. Only authenticated administrators can change it.

For custom servers, serviceHost.proxyEnabled supplies the startup fallback. A saved admin setting takes precedence, including a saved false. The hosted www/main.ts also supports CIVILITY_SERVICES_PROXY=true as a startup fallback; this is not a CLI flag or a framework-wide environment setting. The full option shape:

options: {
  serviceDefinitions?: ServiceDefinition[]          // extra/custom service definitions (default: [])
  serviceHost?: {
    proxyEnabled: boolean                     // default: false
    overrides?: Record<string, Partial<ServiceCapabilities>>   // per-service tweaks
  }
  serviceBundleCredentials?: Record<string, {        // keyed by service name, e.g. "ai.claude"
    secret: Record<string, string>            // e.g. { apiKey: "..." }
    metadata?: Record<string, unknown>
  }>
}

1. Enable the proxy (server-proxy mode) #

Enable Allow service proxying in /admin/services to let the server relay invocations using users' own credentials, host bundle credentials, or no credential for keyless services. Saving a credential does not enable proxying.

Alternatively, set the startup fallback where your custom server is constructed (register the desired service definitions there too):

// main.ts — extend the template's createManager call
const manager = await createManager({
  // …existing options (backend, adminToken), adapters (objectStorage), etc…
  options: {
    serviceHost: { proxyEnabled: true },
  },
})
const app = manager.buildApp()

Security note. CivServices wraps outbound calls in an SSRF-hardened fetch — https/http only, DNS-resolved blocking of private/loopback/link-local/CGNAT/IPv6-ULA ranges, no redirect following. You're still originating outbound traffic from your host, so make sure your egress firewalling allows the provider domains.


2. Register bundle credentials (bundle mode) #

A bundle credential is a host-owned provider key: users without their own key can still invoke the service, and the server meters usage against their tier quota. The app just sees the service as available.

Provide the secret inline, reading it from your environment so it never lands in source:

options: {
  serviceHost: { proxyEnabled: true },     // bundle mode also relays outbound, so the proxy must be on
  serviceBundleCredentials: {
    'ai.claude': { secret: { apiKey: Deno.env.get('ANTHROPIC_API_KEY')! } },
    'ai.openai': { secret: { apiKey: Deno.env.get('OPENAI_API_KEY')! } },
  },
},

The env-var names are your convention, not the server's; set them however you set CIVILITY_AUTH_SECRET. The service-name keys (ai.claude, ai.openai, …) come from the service catalog.

Or register through the admin panel (/admin/services, requires adminToken): pick a service, paste the secret as key=value lines, save. Those credentials are sealed at rest under CIVILITY_AUTH_SECRET and read hot, so registration, rotation, and deletion take effect with no redeploy — and a stored credential overrides an inline one for the same service, so you can hot-rotate a key originally shipped in main.ts. The panel never displays stored values, only field names. Rotating an inline credential is still a redeploy.

Either way, registering a bundle credential is what makes bundleAvailable: true appear for that service in the catalog. Proxying must also be enabled to use it. Without a bundle key, credentialed services require users to bring their own key.

Podcast search and RSS #

The CLI registers podcast.podcastindex and podcast.rssfetch. For a custom server:

import { podcastindex, rssfetch } from '@civility/services/podcast'

// Within createManager options:
serviceDefinitions: ;
;[podcastindex, rssfetch]

Enable proxying in /admin/services. For podcast search, either users save their own Podcast Index key and secret in the app, or the operator selects podcast.podcastindex in the bundle form and enters:

key=YOUR_PODCAST_INDEX_KEY
secret=YOUR_PODCAST_INDEX_SECRET

Podcast Index has no browser CORS support, so a user key alone is insufficient when proxying is disabled. podcast.rssfetch needs no key and becomes usable as soon as proxying is enabled. The admin services table distinguishes host-key, user-key, and credential-free access. Apps that cache the catalog may need to reconnect or reload after a setting changes; the server enforces the current setting on every invocation.


3. Per-service controls #

Each row in /admin/services has an Allowed modes form:

  • Use startup defaults removes that service's saved mode override.
  • Disabled saves an empty mode list. Credentials and grants are retained.
  • Use selected modes saves the checked modes; at least one mode supported by the registered implementation must be selected.

These settings are persisted, audited, and read by both the catalog and server invocation checks without a restart. Saved modes override startup mode settings, while other startup capability overrides (such as CORS) remain unchanged. Both server-proxy and bundle still require the global proxy switch. A service cannot be granted execution modes its implementation does not declare.

Apps caching the catalog may need to reload to see changes. Disabling blocks server invocations immediately, but cannot prevent an app from independently calling a provider directly, outside CivServices.

Custom servers can still use host.overrides as startup fallbacks for modes or other capabilities:

options: {
  serviceHost: {
    proxyEnabled: true,
    overrides: {
      // disable a specific service on this host
      'ai.gemini': { /* narrowed capabilities per ServiceCapabilities */ },
    },
  },
},

Overrides are merged onto the service's declared capabilities. Use them to shape exactly which services and modes your users see. See services spec §11.4.3 for the ServiceCapabilities shape.


4. Credential-free services #

Some services need no key at all — podcast.rssfetch (a server-side RSS fetch, used as a browser-CORS fallback) declares credential: { kinds: [], optional: true }. These work for every user the moment proxyEnabled: true is set: nothing to register, nothing for the user to enter. host.overrides still disables them per deployment.

Services that opt into capabilities.rateLimited — credential-free ones especially, since there's no key to revoke — share one serviceProxy rate-limit bucket, default 20 requests / 5 minutes per user. It resolves through the same base → tier → per-user layering as every other bucket; per-user overrides are in the admin panel.


5. Metering bundle usage (per-user quotas) #

Bundle invocations are metered against a per-user monthly allowance, maxBundleInvocationsPerMonth:

  • Default is 0, which means unlimited.
  • It resolves through startup default → saved server default → tier preset → per-user override — the same as storage quotas. Configure server defaults in /admin/limits.
  • Enforcement requires a service usage store. The built-in backend provides one even without tiers; custom backends without one cannot enforce monthly bundle allowances. Billing/storage snapshot metering is separate and remains tier-dependent.

You can cap self-hosted usage through /admin/limits, or define tiers with different bundle allowances:

const manager = await createManager({
  // …dialect via options.backend, serviceBundleCredentials…
  options: {
    limits: { maxBundleInvocationsPerMonth: 100 }, // base default for everyone
    tiers: {
      free: { limits: { maxBundleInvocationsPerMonth: 20 } },
      pro: { limits: { maxBundleInvocationsPerMonth: 1000 } },
    },
  },
})
const app = manager.buildApp()

Per-user overrides are set from the admin panel (PATCH /admin/users/:id/limits) alongside the storage quotas. When a user exceeds the allowance, invoke returns services.quota_exceeded (HTTP 429) and the app is expected to prompt for an upgrade or a bring-your-own-key path.

See billing for tier setup on the hosted service. For unlimited self-hosted bundles, leave the shared and per-service caps at 0 (and ensure no tier/user override sets a cap).


Deciding what to enable #

You want… Set
Nothing outbound; users bring keys, calls go direct. Nothing — the default. Only client-direct services work.
Users store keys once, server relays. host.proxyEnabled: true.
Provide keys for users (host pays), capped. proxyEnabled: true + bundleCredentials + an allowance in /admin/limits or tiers.
Provide keys, uncapped (personal/community server). proxyEnabled: true + bundleCredentials, with effective caps of 0.

See also #