Skip to content

Security

This document consolidates the server’s security model. See configuration.md for the full env-var reference, transports.md for transport setup, and deployment.md for remote-deployment hardening.

Use uv sync --locked to install the reviewed dependency set. FastMCP is bounded to fastmcp[tasks]>=4.1.8,<4.2; older 4.0.x environments do not contain the current upstream security fixes. The framework, task extension and MCP SDK must be upgraded together through the lockfile rather than independently.

On 2026-11-10, bash scripts/audit_dependencies.sh reported no known vulnerabilities for the refreshed lockfile. This is a point-in-time result, not a guarantee against future disclosures. CI and the commit hook run this audit without vulnerability exemptions.

Upstream release details: FastMCP 4.1.8. Stage upgrades separately, finish active jobs before restarting, and preserve runtime state, artifact storage and any task-snapshot encryption key.

AuthMode (config/env.py) accepts only local and api_key.

Mode Transport Behavior
local (Python default) stdio or loopback HTTP No FastMCP auth provider; a single trusted principal local.
api_key HTTP SharedKeyVerifier, hash-only verification and one non-admin team identity.

Docker, Compose and Terraform default to api_key. build_auth_provider returns None for LOCAL or a SharedKeyVerifier for API_KEY. Fail-closed is structural and startup-time: if MCP_TRANSPORT=http + MCP_AUTH_MODE=local + MCP_HOST is not in {127.0.0.1, ::1, localhost}, Settings construction raises ValueError("HTTP on a non-loopback host requires MCP_AUTH_MODE=api_key.") and the server never starts.

MCP_AUTH_MODE=api_key requires MCP_API_KEY_SHA256, a lowercase 64-character SHA-256 digest. The bearer key must be 32 random bytes encoded as lowercase hex; key generation and rotation use a private file, never command-line secret arguments. The verifier hashes the incoming ASCII key and compares digests with hmac.compare_digest. It does not cache authentication or log credentials. The digest is masked in settings representations. There is no login or OAuth discovery endpoint.

All holders receive principal/tenant shared-team and the fixed SHARED_TEAM_SCOPES allowlist. They share ownership, budget, and concurrency; they can read or cancel each other’s permitted work. There is no per-member audit identity, automatic expiry, or individual revocation. Rotate the key for everyone to remove a member. Identity is independent of the credential, so rotation preserves team history. Switching auth modes is not a data migration. Account-wide asset and moderation scopes are excluded.

TLS, Host/Origin enforcement, body limits, configured rate limits, ownership checks, and remote filesystem restrictions apply unchanged. Redis snapshot encryption is required for authenticated Redis task backends: a hash-only server configuration does not eliminate raw bearer credentials from live request/task context. Reload by recreating the application process/container after draining work; editing .env alone does not revoke running access.

get_principal(ctx) (runtime.py) resolves the principal identity from the verified internal bearer-token context. SharedKeyVerifier supplies sub="shared-team", tenant_id="shared-team" and the fixed ordinary scopes; clients cannot override these by submitting claims.

Generic bearer-claim extraction remains internal so ownership boundaries can be tested independently of the shared-key verifier:

  • sub claim → token.subject → token.client_id (first truthy str wins). Missing → PermissionError("The access token is missing a principal identity.").
  • Tenant is read from the fixed "tenant_id" claim key. Missing/non-string → PermissionError. This key is not configurable.
  • A missing token → PermissionError("An authenticated access token is required.").

There is no anonymous remote principal; shared-key HTTP fails closed. The only way to get an is_local principal (principal_id == "local" with transport == "stdio") is LOCAL mode, which returns PrincipalContext() untouched (local/local, empty scopes, transport="stdio"). This holds for loopback HTTP too, and is intentional: it is what lets all clients of one shared loopback server see each other’s background jobs.

The trust implication is explicit: with MCP_AUTH_MODE=local over loopback, any local process or user that can reach the port acts as the local principal — including billable tool calls and artifact or job reads. This matches the stdio trust model, but the port is reachable by every local account, so bind loopback only and do not expose it through a proxy.

A frozen Pydantic model (security/auth_context.py):

Field Type Default
principal_id str "local"
tenant_id str "local"
scopes frozenset[str] frozenset()
transport Literal["stdio", "http"] "stdio"

is_local returns principal_id == "local" and transport == "stdio". AuthContext is a compatibility alias for PrincipalContext.

component_auth(settings, *scopes) returns None in LOCAL mode, or require_scopes(*scopes) (a FastMCP AuthCheck) in API_KEY mode. The tool → scope mapping is the scope column of the static tool catalog (tools/_catalog.py), applied by server.py::register_tools:

Scope Protects
seed:audio:generate seed_audio_generate (single clip or variations)
seedream:generate seedream_generate_image (generation, editing, variations, and dry runs)
seedance:create seedance_create_task (every Seedance model, including variations and dry runs)
gen:read gen_task_get, gen_task_list (Seedance, Hyper3D and Hitem3d tasks)
gen:delete gen_task_cancel_or_delete
seed:asr:transcribe speech_to_text
understanding:read seed_understand, seed_audio_understand
hyper3d:create hyper3d_create_task
hitem3d:create hitem3d_create_task
omnihuman:create omnihuman_create_task
omnihuman:read omnihuman_get_task
omnihuman:cancel omnihuman_cancel_task
vod:enhance vod_enhance_video
vod:transcode vod_transcode_video
vod:subtitle:add vod_add_subtitles
vod:subtitle:remove vod_remove_subtitles
vod:read All MediaKit task polling tools
vod:extract vod_separate_audio
media:upload media_upload, seed_media_persist_url
media:presign media_presign
artifacts:read MCP resource seed-media://artifacts/{artifact_id}, seed_media_get_artifact, seed_media_export_artifact

These ordinary scopes form the fixed shared-team allowlist. They are not per-user roles and cannot be changed through client claims or configuration. Account-wide assets:* and moderation:* scopes are excluded, so shared-key callers cannot invoke those administrative tools even if they are registered. Trusted local administration still requires the relevant provider gates.

The catalog retains assets:read, assets:write, assets:verify and assets:delete as permission labels for asset operations. None is granted by the shared key; these tools are available only through trusted local mode with the required provider credentials and feature flags.

The catalog label moderation:read protects ark_moderation_get and is also excluded from the shared key. Complete AK/SK plus BYTEPLUS_MODELARK_MODERATION_ENABLED=true register it for trusted local stdio/local-mode loopback use only; they do not grant shared HTTP access.

Create scopes are per product because that is where spend happens; read and delete scopes are shared (gen:read, gen:delete) because the ownership store already limits every principal to its tasks. Every shared-key member is that same principal, including for result reads and cancellations.

ark_job_* and ark_list_models need an authenticated principal but no scope: job tools enforce the target tool’s scope at submit time, and ark_list_models returns only configured model IDs and limits.

The seed-health://status resource and the /health, /ready, /metrics routes are not scope-protected at the FastMCP layer. Seed Audio and speech-to-text tools are registered only when BYTEPLUS_SEED_SPEECH_API_KEY is set; Seedream/Seedance tools only when BYTEPLUS_MODELARK_API_KEY is set; vod_enhance_video, vod_transcode_video, vod_add_subtitles, vod_remove_subtitles, vod_separate_audio, and vod_get_task only when BYTEPLUS_VOD_MEDIAKIT_API_KEY is set. The media_upload and media_presign tools are registered only when object storage credentials are set (TOS: TOS_ACCESS_KEY / TOS_SECRET_KEY / TOS_BUCKET, or S3: S3_ACCESS_KEY / S3_SECRET_KEY / S3_BUCKET with OBJECT_STORAGE_BACKEND=s3).

BYTEPLUS_MODELARK_ACCESS_KEY / _SECRET_KEY (plus _SESSION_TOKEN for STS keys) sign ModelArk OpenAPI requests with BytePlus V4 HMAC-SHA256 (providers/byteplus_openapi/signing.py). They are startup configuration only and are never logged, echoed, or accepted as tool arguments. The ark_asset_* tools are registered only when both keys are set. Asset management acts on the whole BytePlus account rather than per MCP principal. Shared-key HTTP excludes every asset scope; use trusted local stdio for administration. The real-person verification h5_link embeds temporary credentials: it is returned to the caller but never logged. asset://<asset_id> references are validated by shape and never fetched by the server; CreateAsset source URLs pass the standard URL policy. See assets.md.

ark_moderation_get queries account-wide records authorized by provider credentials, without tenant or task-ownership filtering. Local-mode loopback therefore exposes this access to any local process that can reach the port; do not proxy it. Discovery does not prove Advanced Creation Rights, whitelist activation or IAM GetModerationResult.

The tool is foreground-only, excluded from ordinary jobs and native tasks. Authorized invalid inputs are rejected generically before framework validation can log private values. Malformed known response fields produce generic INVALID_RESPONSE, not raw bodies or validation inputs. IDs, reasons and details are not added to logs, metrics or server-side result storage. Treat provider explanations as untrusted text, never instructions or proof of safety. Empty reasons and NotFound.Id do not establish approval. Live provider success is unverified; see moderation.md and the contract.

Public publication of this minimal contract is explicitly approved. Private Lark URLs, restricted source text, real fixtures and screenshots are excluded; published examples must be synthetic.

Object storage access key and secret key are loaded from environment variables at startup (TOS_ACCESS_KEY / TOS_SECRET_KEY or S3_ACCESS_KEY / S3_SECRET_KEY) and never accepted as tool arguments. The bucket is private — presigned URLs grant temporary read access to individual objects. Object keys are server-generated UUIDs under a caller-supplied prefix; key_prefix is sanitized to alphanumeric, -, _, and /. File-path input is restricted to the stdio transport to prevent remote file reads over HTTP.

Uploaded object keys are recorded in the SQLite object_key_ownership ledger keyed by (principal_id, tenant_id). media_presign verifies the caller owns each key (an unowned key returns NOT_OWNED for that key only) before minting a read URL; a remote principal cannot re-presign another tenant’s object. In LOCAL mode, unrecorded keys remain presignable by the single local principal. A successful record or require_owner refreshes the row’s created_at timestamp, so regularly presigned keys are not expired by the state sweeper. Rows are pruned by the background state sweeper after STATE_PRUNE_MAX_AGE_DAYS (default 30) of inactivity; a long-lived key that has not been presigned within that window must be re-uploaded before it can be presigned again by a remote principal.

Enabled in __main__.py for HTTP transport via FastMCP-native guards (host_origin_protection=True plus allowed_hosts/allowed_origins). This is not a custom middleware in this repo.

Env var Default Notes
MCP_ALLOWED_HOSTS 127.0.0.1,localhost,[::1] comma-separated
MCP_ALLOWED_ORIGINS "" (empty → all browser origins rejected) each must be an http/https URL with a hostname

When deploying behind a public hostname, set both the public hostname (in MCP_ALLOWED_HOSTS) and the allowed browser origins (in MCP_ALLOWED_ORIGINS).

Body-limit middleware (security/http_middleware.py)

Section titled “Body-limit middleware (security/http_middleware.py)”

RequestBodyLimitMiddleware (ASGI) — the only custom ASGI middleware shipped in security/. Wired for HTTP transport only.

Env var Default Notes
MCP_HTTP_MAX_BODY_BYTES 314_572_800 (300 MiB), ge=1 rejects oversized bodies; sized to inline the largest supported Base64 media upload (200 MiB video inflates ~4/3x)

Behavior: reads Content-Length; if > max_bytes → 413 "Request body too large"; on unparseable Content-Length → 400. It also wraps receive to enforce the limit on streamed bodies; if the response has already started, it re-raises RequestBodyTooLarge (the connection errors out rather than sending a clean 413 mid-stream).

Rate limiting (security/http_middleware.py)

Section titled “Rate limiting (security/http_middleware.py)”

RateLimitMiddleware (ASGI) — a per-client-IP token bucket rate limiter, wired for HTTP transport only when RATE_LIMIT_RPM > 0. Disabled by default.

Env var Default Notes
RATE_LIMIT_RPM 0 (disabled) Maximum HTTP requests per minute per client IP
RATE_LIMIT_BURST 0 (defaults to RATE_LIMIT_RPM) Token bucket burst capacity

Behavior: each client IP gets an in-memory token bucket. The refill rate is rpm / 60 tokens per second. Each request consumes one token. When the bucket is empty, the middleware returns 429 "Rate limit exceeded" with a Retry-After header indicating the seconds until the next token is available, plus X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers so well-behaved clients can self-throttle. The bucket dict is protected by an asyncio.Lock, and expired buckets are evicted once more than 10,000 keys are tracked.

Env var Default Notes
RATE_LIMIT_TRUST_PROXY_HEADERS false Key buckets on the first X-Forwarded-For entry instead of the socket peer IP

Enable proxy headers only behind a proxy that overwrites X-Forwarded-For. Otherwise a client can choose its own bucket key and evade the limit.

Both ASGI middlewares are applied by HardenedFastMCP.http_app (server.py) whenever MCP_TRANSPORT=http, so they are active whether the server starts through python -m ark_mcp or fastmcp run.

SSRF-safe downloader (security/safe_downloader.py)

Section titled “SSRF-safe downloader (security/safe_downloader.py)”

SafeDownloader downloads provider media (for copy_from_trusted_url) with two-layer SSRF defense. Constructor defaults: timeout=120.0s, connect_timeout=30.0s, max_attempts=3, follow_redirects=False, trust_env=False (ignores HTTP_PROXY/HTTPS_PROXY/NO_PROXY). The runtime builds it from ARTIFACT_DOWNLOAD_TIMEOUT_SECONDS, BYTEPLUS_CONNECT_TIMEOUT_MS, and ARTIFACT_DOWNLOAD_MAX_ATTEMPTS.

Retryable failures (timeouts, network errors, 408/429/5xx) are retried with 1s, 2s, 4s, … backoff. Policy failures (untrusted host, redirect rejection, oversize, expired source) are never retried, so retries cannot widen what the downloader accepts.

download(url, *, trusted_hosts, max_bytes, max_redirects=5):

  1. validate_url(current_url) — full SSRF validation (scheme, host, DNS, IP-class denial) returns pinned public IPs.
  2. If not trusted_hosts(hostname) → ValueError (an application host allowlist on top of the IP-level check).
  3. _request_pinned(validated, max_bytes=...) — IP pinning: connects to validated.addresses[0] while preserving the original Host header and TLS SNI (sni_hostname), preventing DNS rebinding between validation and connection. The connect URL replaces the netloc with the IP literal (IPv6 bracketed).
  4. Redirects are handled hop-by-hop: each Location is revalidated from scratch (DNS + IP + host policy all re-applied). Missing Location → ValueError; too many redirects → ValueError.
  5. Streaming size cap: if Content-Length > max_bytes → ValueError; chunks are accumulated and checked against max_bytes after each extend.

FilesystemArtifactStore restricts copy_from_trusted_url to provider hosts via suffix allowlist: .bytepluses.com, .byteplus.com, .bytedance.com, .bytednsdoc.com, .volces.com, .byteplusvod.com, .tos-ap-southeast.bytepluses.com. A caller may extend the list for one download only: omnihuman_get_task additionally trusts .tiktokcdn.com, where OmniHuman output videos are served, so seed_media_persist_url and speech_to_text still reject that host.

seed_media_persist_url accepts a caller-supplied URL, so it relies on the same controls: the URL goes through copy_from_trusted_url with this host allowlist, full SSRF validation and IP pinning, per-hop redirect re-validation, and the per-media-type size limits. Any host outside the allowlist is rejected; the tool cannot be used to fetch arbitrary URLs. It requires the fixed team’s media:upload scope in api_key mode.

For VOD AI MediaKit, video processing and artifact persistence are separate outcomes. The tool always preserves a successful provider output URL for the authorized caller, then best-effort downloads it through this SSRF-safe path. Outputs above the 200 MiB video limit or failing host/MIME/download/storage checks return persistence="failed" without changing provider success into a provider failure. Full source URLs and credentials are excluded from logs and safe error messages.

Tools that write to a caller-chosen local path — output_path/output_dir on generation and get tools, save_to on seed_understand and seed_audio_understand, and destination_path on seed_media_export_artifact — share one policy in security/output_paths.py:

  • stdio only. The client and server must share a filesystem; the fields are rejected on HTTP transport.
  • Allowed roots. The client’s MCP roots (roots/list, file:// URIs only, 2-second timeout) are used when available; otherwise OUTPUT_ROOTS (comma-separated absolute directories). With neither, path writing is disabled and every such field is rejected. A background worker has no MCP session and so no MCP roots: local writes inside ark_job_submit are checked against OUTPUT_ROOTS only.
  • Containment. The path must be absolute and resolve inside a root. A file target cannot be a directory or a root itself.
  • Pre-flight. Paths are validated before any billable provider call, so a rejected path never produces paid output.
  • TOCTOU-safe writes. Missing parent directories are created one level at a time with containment re-checked. The final directory is opened with O_NOFOLLOW, its real location is re-checked against the roots, and the file is published atomically through the directory descriptor. A symlink swapped in after validation cannot redirect the write.
  • No silent overwrite. Publishing is exclusive unless overwrite=true; a destination that already holds identical bytes (same SHA-256) is a success.

Breaking change for seed_media_export_artifact: destination_path must now be absolute and inside an allowed root, and an existing file is no longer silently overwritten (pass overwrite=true).

Exception: UrlValidationError(ValueError).

  • Blocked hostnames (literal): 169.254.169.254 (AWS metadata), metadata.google.internal (GCP), 100.100.100.200 (Alibaba), fd00:ec2::254 (AWS IPv6 metadata).
  • Allowed schemes: https always; http only when the caller passes allow_http=True. file:// is never allowed.
  • No credentials in URLs (userinfo rejected).
  • Hostname is IDNA-encoded → ASCII → lowercased.
  • Ports: only 443 (https) and 80 (http) are allowed; any other explicit port is rejected. Default is 443 (https) / 80 (http).
  • DNS + IP denial: resolve_public_addresses resolves the hostname (or uses a literal IP directly), then denies any address that is not globally reachable — is_private, is_loopback, is_link_local, is_multicast, is_reserved, is_unspecified, or not is_global (which additionally covers CGNAT shared space 100.64.0.0/10). For IPv6, embedded IPv4 transition formats (ipv4_mapped, sixtofour, teredo[1]) are recursively checked.

validate_url combines syntax validation + DNS resolution and returns a ValidatedUrl(url, parsed, hostname, port, addresses).

Exception: MediaValidationError(ValueError).

MediaLimits (returned by get_media_limits(), no env override in this module) cap provider-bound media:

Limit Default
audio_max_bytes 10 MiB
audio_max_seconds 30
image_max_bytes 10 MiB
video_max_bytes 200 MiB

Allowed MIME types:

Category MIME types
Audio audio/wav, audio/x-wav, audio/wave, audio/mpeg, audio/mp3, audio/pcm, audio/x-pcm, audio/ogg, audio/ogg;codecs=opus, audio/webm
Image image/jpeg, image/jpg, image/png, image/webp
Video video/mp4, video/quicktime

check_base64_size estimates decoded size as (len(stripped) * 3) // 4 (without full decode); decode_base64_safely validates then decodes. check_audio_duration_from_base64 decodes WAV (RIFF) headers and enforces audio_max_seconds for Base64 audio references; non-WAV formats (MP3, PCM, OGG) cannot be measured without a full decoder and are skipped — the provider enforces the limit server-side for those. This preflight is best-effort: it trusts the declared data chunk size, so a crafted header with an under-reported size could bypass it. The provider enforces the 30-second limit server-side regardless.

MCP_INLINE_MEDIA_MAX_BYTES (default 8 MiB) lives in config/env.py, not here. It caps inline MCP media returned to the client; the per-type MediaLimits above cap provider-bound media. The two are independent.

  • truststore.inject_into_ssl() runs at module import in server.py and __main__.py, so Python uses the macOS Keychain for TLS verification.
  • Provider base URLs (BYTEPLUS_MODELARK_BASE_URL, BYTEPLUS_SEED_AUDIO_BASE_URL, BYTEPLUS_VOD_MEDIAKIT_BASE_URL) are validated at settings load: must be https:// with a hostname and no embedded credentials; trailing slash stripped.
  • VOD AI MediaKit requests are authenticated with Authorization: Bearer ${BYTEPLUS_VOD_MEDIAKIT_API_KEY}; the key is never logged, returned, or accepted as a tool argument.
  • Inline subtitle_text is treated as sensitive content and is redacted from structured logs together with prompt, subtitle, media URL, and credential fields.

get_settings() is @lru_cache(maxsize=1); refresh_settings() clears the cache. Operators must recreate the running application after configuration changes; refreshing a settings cache alone does not rebuild the verifier. Follow key rotation to revoke a key.

MCP task results use the same tenant/principal boundary as provider tasks. TenantTasksExtension records task ownership under the mcp namespace in the runtime ownership database and checks it before get, update, or cancel. The internal bearer context must include the fixed tenant_id claim key. FastMCP’s own client/subject namespace remains an additional check, not the application’s source of tenant isolation. Ownership tests retain generic bearer identities to verify cross-tenant rejection even when client and subject match. Production shared-key requests all resolve to shared-team; these checks do not isolate members of the team.

The ordinary ark_job_* tools reuse this boundary. Submission resolves only an immutable allowlist of task-enabled tools, requires the target tool’s exact scope before queueing, and claims the server-generated job ID for the current tenant and principal. Capability discovery returns only configured targets permitted by the caller. Get and cancel check ownership before consulting the task backend, and unknown or cross-principal IDs never return another caller’s result. Arguments, prompts, URLs, and result bodies are not added to logs or metric labels.

Authenticated Redis task backends require snapshot encryption at startup. Set FASTMCP_TASKS_ENCRYPTION_KEY from a secret manager with at least 32 random characters. FastMCP snapshots contain caller tokens and inbound HTTP headers; without encryption these would be stored as plaintext. Use backend access controls and TLS as well: snapshot encryption does not encrypt every task argument or media result. Preserve the same key for retained tasks; replacing it makes old snapshots unreadable and their execution fails closed.

Required-task workers atomically claim their MCP task ID in SQLite before provider work. Claims survive restarts, so redelivery of an already-started task fails with an ambiguous-outcome/reconciliation message instead of automatically repeating a billable operation. This is not an exactly-once provider guarantee: a new submission has a new ID, and deleting runtime state removes its execution history. Keep the single-replica restriction and preserve the database whenever retaining a Redis queue. Ownership/execution rows follow the existing state retention policy; retained queue state must not outlive that history.

The old jwt auth mode is rejected. Retired MCP_JWT_*, MCP_TENANT_CLAIM and MCP_PUBLIC_BASE_URL settings are not used. There is no automatic transfer of former user or local ownership to shared-team. Preserve SQLite, artifacts, Redis and the existing snapshot encryption key while migrating clients. See the migration procedure.