wove.security

wove.security contains the shared security helper used by Wove’s network executors. Most projects only need the security setting in an environment definition; worker-service implementers can use NetworkExecutorSecurity to validate incoming Wove requests before deserializing task payloads.

Normal Configuration

Use an environment variable when the submitting process and worker service share a secret:

import wove

wove.config(
    environments={
        "workers": {
            "executor": "https",
            "executor_config": {
                "url": "https://workers.internal/wove/tasks",
                "security": "env:WOVE_WORKER_SECRET",
            },
        }
    },
)

The security="env:WOVE_WORKER_SECRET" shorthand creates signed network executor requests. Wove signs the serialized command body with HMAC-SHA256 and sends the signature as transport-appropriate headers or metadata.

Security Guarantee

Signed network executor requests authenticate the Wove process that submitted the command frame and detect payload tampering. Each signature covers the transport name, target path or method, timestamp, nonce, and SHA-256 hash of the serialized command body.

The nonce cache rejects replayed signed requests within the configured clock-skew window. TLS is still responsible for confidentiality, which is why Wove requires secure non-local network executor transports unless executor_config.insecure=True is set for development.

Worker Service Verification

A worker service should verify the request before decoding dispatched callables or arguments.

from fastapi import Request
from wove.security import NetworkExecutorSecurity

security = NetworkExecutorSecurity.from_config("env:WOVE_WORKER_SECRET")


async def wove_tasks(request: Request):
    raw_body = await request.body()
    security.verify_headers(
        headers=request.headers,
        transport="http",
        target=request.url.path,
        body=raw_body,
    )

For gRPC, use verify_metadata(...) with the method path as the target.

Supported Modes

Shape

Meaning

"env:WOVE_WORKER_SECRET"

Signed requests using a secret stored in an environment variable.

{"type": "signed", "secret_env": "WOVE_WORKER_SECRET"}

Explicit signed mode.

{"type": "signed", "secret": "..."}

Signed mode with an inline secret. Useful in tests.

{"type": "bearer", "token_env": "WOVE_WORKER_TOKEN"}

Bearer token mode for existing worker services.

{"type": "none"}

No network executor authentication. Only appropriate for local development.

API Details

class wove.security.NetworkExecutorSecurity(*, mode='none', secret=None, key='default', token=None, clock_skew_seconds=300.0, remember_nonces=True)[source]

Bases: object

Authentication helper for Wove network executors.

Parameters:

  • mode (str)

  • secret (Any | None)

  • key (str)

  • token (str | None)

  • clock_skew_seconds (float)

  • remember_nonces (bool)

classmethod from_config(config)[source]

Build network executor security from an executor security config value.

Parameters:

config (Any)

Return type:

NetworkExecutorSecurity

headers_for(*, transport, target, body)[source]

Return HTTP/WebSocket headers for one outbound network executor request.

Parameters:
Return type:

Dict[str, str]

metadata_for(*, transport, target, body)[source]

Return lowercase gRPC metadata pairs for one outbound network executor request.

Parameters:
Return type:

Tuple[Tuple[str, str], …]

verify_headers(*, headers, transport, target, body)[source]

Verify HTTP/WebSocket network executor request headers.

Parameters:
Return type:

None

verify_metadata(*, metadata, transport, target, body)[source]

Verify gRPC network executor request metadata.

Parameters:
Return type:

None