Security and data handling

TaskSultan runs on your machine, with your data. The state root holds the local control-plane records, the vault holds secret values. Run evidence goes to an artifacts folder you choose. Nothing is sent anywhere unless you point the authoring step at a remote model.

#Where data lives

The Orchestrator state root holds the local records:

• vault.json and vault-audit.ndjson, the credential store and its custody journal.
• principals.json, the identity registry.
• governance.ndjson and approvals.json, the governance history and the enforcement record.
• action-centre.ndjson, the human-in-the-loop journal.
• jobs/, evidence/ and queues/, what ran and what it left behind.
• robots/, schedules/, deployments/, suites/ and suite-runs/.
• state-gc.ndjson, the run-state collection journal.

Run artifacts (screenshots, traces, state.json, logs.txt, summary.json, evidence-manifest.json) are written under the artifacts root.

A protected class is never collected by run-state maintenance at any age: the vault and key material, governance.ndjson, principals.json, approvals.json, the request and Action stores, robots/, schedules/ and deployments/.

#What leaves the machine

By default, nothing. There is one outbound path. It is authoring only. When you generate with a remote model (robot generate --remote, or the Studio's remote option), the brief and the curated generation context are sent to the endpoint named by TS_MODEL_API_BASE. With the scripted model, an injected artifact, or TypeScript you write yourself, no data leaves.

Licence verification makes no network call: the robot checks a signed lease with a public key. Renewal is a separate, explicit act by your own tooling. Execution never calls a model, so a run sends nothing anywhere.

#Secrets

Credentials live in the vault by name. An automation asks for a name (ctx.credentials.get(name)) and never holds a value in code. At dispatch the Orchestrator resolves the requested names and injects them into the Robot child's environment as TS_CRED_<NAME>. A value never appears in a command line, a suite file, a config file or a log.

An encrypted vault (vaultVersion 2) gives each secret its own item key, sealed under a wrapping key for the state root, with AES-256-GCM per record. The default wrapping-key file lives outside the state root, in your user data directory, keyed by a hash of the root so several roots stay separate. The only route from a plaintext vault to an encrypted one is vault encrypt --migrate; there is no silent upgrade. vault rotate <name> re-seals one credential with a fresh item key.

Injection respects an allow-list. The default is every non-production environment; prod requires an explicit include. A credential restricted elsewhere is refused before the Robot is spawned. A name that is missing or ambiguous fails closed rather than guessing.

npx tsx orchestrator/cli.ts vault init
npx tsx orchestrator/cli.ts vault set acme --type credential --envs dev,staging --secret-stdin
npx tsx orchestrator/cli.ts vault list
npx tsx orchestrator/cli.ts vault show acme
npx tsx orchestrator/cli.ts vault encrypt --migrate
npx tsx orchestrator/cli.ts vault rotate acme
npx tsx orchestrator/cli.ts vault doctor --strict
npx tsx orchestrator/cli.ts principals add <id> --roles operator,approver

vault list and vault show work keyless and render names, field names and fingerprints, never values. A fingerprint is 12 hex characters of a SHA-256; it changes on a value change and on a rotation, so lineage is traceable without disclosure. --via <tag> records which surface asked for a write. Admin credentials are bearer secrets over a file registry, stored only as a scrypt hash, with the secret shown once when it is generated.

#Audit trails

Every trail is append-only and value-free.

• governance.ndjson records approve, consume and delete rows, each attributed to a verified principal id.
• vault-audit.ndjson records one row per successful custody change: the kind, the action, the name, the field names, the fingerprint and the previous fingerprint.
• state-gc.ndjson records each run-state removal, written after it succeeds.
• Licence events record issued, renewed, activated, deactivated, migrated and denied, each with a reason.
• Each job row carries a credential lineage: names and fingerprints, never values.

A refused write writes no audit row, because it did not happen. A credential value is never printed. There is no supported way to read one back.