Scriptum Auth And Access

Last validated: 2026-05-11

This document describes how tenant identity and access control are enforced in current Scriptum runtime.

Identity Inputs Required By API

scriptum-api derives tenant context from gRPC metadata headers:

• x-organization-id
• x-organization-name

If either is missing, API returns Unauthenticated for most business RPCs.

Bearer Token Handling

cli-scriptum attaches:

• authorization: Bearer <token>
• x-organization-id and x-organization-name when configured

Important runtime note:

• In this codebase, tenant extraction is done from metadata headers.
• Token validation/authorization policy is expected to be enforced by platform/gateway layers and optional IAM integration, not by deep token parsing inside Scriptum handlers.

Tenant Isolation Model

All script and thread data is scoped under tenant storage prefix:

• tenants/{org_id}/...

Thread index entries are also org-scoped in NATS KV keyspace:

• {org_id}.{script_name}.{thread_id}

This keeps script/thread metadata isolated by org ID.

IAM Resource Registration

Scriptum supports optional IAM registration for script resources.

What gets registered

• Resource kind: script
• DRN shape: drn:dodil:scriptum:{org_id}:{script_name}
• Scopes include script CRUD/versioning/thread-related scope names

When registration happens

• On CreateScript, Scriptum registers IAM resource.
• On DeleteScript, Scriptum deregisters IAM resource.

Failure behavior

• CreateScript is effectively transactional with IAM: if IAM registration fails, registry create is rolled back.
• DeleteScript may return error if IAM deregistration fails after registry delete.

IAM Startup Behavior

Code defaults in ServerConfig:

• SCRIPTUM_IAM__ENABLED=true
• SCRIPTUM_IAM__FAIL_ON_INIT_ERROR=true

Operational drift to know:

• .env.example still documents false/false style defaults.
• If operators rely only on .env.example comments, behavior may be surprising.

gRPC mTLS

• Controlled by SCRIPTUM_GRPC__ENABLE_MTLS.
• In SCRIPTUM_ENVIRONMENT=production, mTLS must be enabled or API startup fails.
• Certs are loaded from Vault env settings when enabled.

Service Discovery Dependency

• IAM manager resolves IAM endpoint via service discovery manager.
• If IAM is enabled but service discovery is disabled/unavailable, behavior depends on SCRIPTUM_IAM__FAIL_ON_INIT_ERROR.

Environment Variable Access Surfaces

Tenant env APIs

• SetEnvVar, GetEnvVar, ListEnvVars, DeleteEnvVar, ImportEnvVars

Script overlay env APIs

• GetScriptEnv, UpdateScriptEnv

Effective env merge semantics

• Base: tenant env
• Overlay: script env
• Merge rule: non-empty script value overrides; empty script value defers to tenant

Sensitive Data Caveat

ListEnvVars currently returns both keys and values in API responses.

• Proto tool description says values are not returned for security.
• Runtime implementation currently includes values.
• Treat CLI/API output for env listing as sensitive.

Access Control Gaps To Be Aware Of

1. Tool registration/get methods are unimplemented server-side.
2. Thread cancel is unimplemented.
3. Artifact listing is unimplemented.
4. Some scope annotations in proto are broader than currently implemented behavior.

Recommended Guardrails

1. Enforce bearer validation and org header integrity at ingress/gateway.
2. Keep IAM enabled in production and fail fast on IAM init errors.
3. Restrict who can call env listing APIs until keys-only behavior is enforced.
4. Treat org ID as canonical tenant isolation key in observability and audit records.