Files
openworker/harness/server-reference/AUTHORIZATION.md
Rohit PrasadandDevika Verma d53e058eda Introduce OpenWorker Harness SDK (in beta), agent service cluster and relevant developer documentation (#844)
Allow developers to easily build AI apps without worrying about the harness part.
Bundles the Rust agent runtime as a SDK (Rust and TypeScript) for building desktop and web applications. Applications can manage a local harness or connect to an authenticated harness service on k8s with separately scaled workers and sandbox execution.

The implementation is primarily contained in harness/, with deployment tooling in deploy/, Markdown guides in docs/harness/guides/, and the static documentation site in docs-site/. It does not replace the existing Python harness or migrate OpenWorker Desktop.

Co-authored-by: Devika Verma <devikaverma11@gmail.com>
2026-11-06 09:45:20 -08:00

7.9 KiB
Raw Permalink Blame History

API authorization

Authorization answers who may use which session. It is independent of the agent's tool approvals, allowed files/network, credentials and sandbox policy. An administrator API key is not a tool-policy bypass.

App key → API node → PostgreSQL credential + session check
                             │
                   command + identity + audit commit
                             │
                      worker → tool policy → sandbox

Roles and scope

Role Authority
observer Read authorized sessions, receipts, progress, artifacts and API health.
operator Also create sessions in explicitly granted environments, submit turns, answer/approve/cancel and publish artifacts in scope.
administrator All sessions; issue/list/revoke credentials and read security audit.

Every non-admin key also has immutable scope: all, owned, or sessions with exact existing IDs. owned means sessions created through the API by that principal, not just by that particular key. Rotation can retain ownership by using the same principal. An exact-session key cannot create new sessions. Operators may create only in administrator-granted environments; an empty list grants no creation. Session listing filters before pagination. Old/trusted-worker-created sessions have no inferred owner: use explicit IDs or all to grant access. Role/scopes must be changed by issuing a new key.

The local reference bootstraps a trusted administrative key for its test CLI and a separate observer for the console. Partner applications should receive an operator scoped to their principal/sessions/environments, not that admin key.

Provisioning and rotation

The deployment owner explicitly runs migrate, then auth-bootstrap, using the private api_token_file and actor in reference configuration. Bootstrap only creates the first administrator in an empty registry. It does not reset an existing registry, silently accept a new file token, or revive a revoked key. There is no HTTP bootstrap endpoint. API authentication uses PostgreSQL, not a master-key file fallback. Database/OS administrators remain trusted.

Generate each bearer from at least 32 random bytes with a cryptographic RNG; encode hex or URL-safe characters (32–256 characters accepted). Store it in a private file or secret manager. Syntax validation cannot detect a weak password. Never put keys in URLs, command arguments, logs, issues or source control. Only a domain-separated SHA-256 digest is stored in PostgreSQL; metadata and audit endpoints return neither bearer nor digest. Losing the bearer requires issuing a new key. V1 has explicit revocation, not automatic expiration.

Example private operator.json (replace the granted environment ID):

{
  "principal": "example-app",
  "role": "operator",
  "scope": { "kind": "owned" },
  "environments": ["env_existing_environment_id"]
}

From harness/, with a valid administrator key in configured api_token_file:

target/debug/openworker-server-reference --config /private/reference.json auth-bootstrap
target/debug/openworker-server-reference --config /private/reference.json auth-issue --spec /private/operator.json --token-file /private/operator-token --request-id example-key-001
target/debug/openworker-server-reference --config /private/reference.json auth-list
target/debug/openworker-server-reference --config /private/reference.json auth-revoke --credential-id key_to_revoke

Issue is idempotent only for the same request ID, principal issuing it, token and spec. Replaying a revoked issuance returns the revoked record, never a new active key. Clients must inspect revoked. Rotate by issuing a distinct token/request ID, switching clients, and revoking the old key. Revoking the last active admin is rejected; provision/test another administrator before rotating that key. Configuration is still managed by the deployment owner, not a remote shell or arbitrary configuration-edit API.

HTTP additions

All endpoints require Authorization: Bearer …, including health. All unmatched route/method combinations are denied. JSON endpoints reject unknown fields.

Method/path Request / response
GET /auth/me Any active key → resolved principal, credential ID, role, scope, environments.
POST /credentials Admin; {request_id, spec, token} → {id, request_id, spec, revoked}.
GET /credentials?after=KEY_ID Admin; {credentials, next_after}, up to 100 records.
POST /credentials/KEY_ID/revoke Admin; idempotent, returns revoked metadata.
GET /security/audit?after=0 Admin; up to 100 events plus next_after.

Missing/invalid/revoked bearer → 401; insufficient authority/out-of-scope ID → 403; malformed spec → 400; conflicting issuance/last-admin revoke → 409; unconfigured/unavailable storage → service error. No authentication fallback when PostgreSQL is unavailable. Use TLS outside the loopback-only reference; credential issuance bodies are secrets and must be excluded from proxy logs.

Revocation, audit and streaming

Each API request checks the shared registry. Mutations recheck and lock the key in the same transaction that admits the command and writes its security audit. Revocation waits for previously admitted transactions, then prevents new ones on every node. Already accepted commands or started tool effects are not cancelled or rolled back by revoking a key; use an authorized cancellation.

SSE rechecks every event read (250ms polling); failure closes the stream with a generic reconciliation error. Downloads recheck before each object chunk; uploads recheck incoming chunks and the final ready-publication transaction. Previously authorized/buffered bytes may finish; they cannot be retracted. An interrupted upload can leave pending/orphan objects. Revocation does not grant permission to resume or reconcile those objects.

Durable audit records principal/key, operation, session/request/target IDs and outcome, not prompts, results, bearer values or hashes. Mutation audit failure rolls back admission. admitted is not proof the external effect succeeded; some exact retries also create admission records. Identified authorization denials are best-effort audit; reads/unknown-key attempts are not a comprehensive access log. Add ingress rate limits, security monitoring and an audit retention policy for production. Audit appends serialize through commit to keep cursors safe across concurrent transactions; benchmark this shared append point at scale. The registry currently caps issuance at 1,024 records, including revoked tombstones; no automatic pruning/resurrection.

Boundary and remaining work

The reference API is loopback-only and rejects browser Origin requests. The console verifies an observer key at startup, keeps it server-side, and has its own distinct browser login key. Its proxy allowlist is additional defense, not the authority boundary: direct observer API mutations are also denied.

This is not physical tenant isolation. Intentionally shared sandboxes have shared filesystem/network authority even when session metadata is scoped. Use separate environments/credentials for mutually untrusted principals. Health includes service-level telemetry counters, not session content. Unscoped worker/store calls and in-process SDK hosts with DB/OS access remain trusted; authorized() guards the documented API operations, not every generic store/SDK method against hostile Rust code. No Desktop/stdio/local SDK change.

SSO, user-directory integration, expiry, fine-grained approval-only roles, per-coworker/model/resource admission ceilings, tenant quotas, distributed rate limits and production TLS/IAM remain integration work. In particular an operator can choose existing session-creation permission modes; API roles do not define an additional organization-wide tool-policy ceiling.

Design guidance: OWASP authorization recommendations.