docs/SECURITY.md

Security Notes

Token model

The orchestrator uses Hugging Face OAuth. Do not store a global admin HF_TOKEN in the Space.

The signed-in user's OAuth token is passed to Hugging Face Jobs as a secret named HF_TOKEN. The worker must not write this token to the Bucket, traces, reports, generated files, events, or logs.

Resource ownership

Generated Spaces are constrained to the signed-in user's namespace and are private by default.

Validation is limited to Spaces under the signed-in user's namespace. This prevents one user from using the validation workflow to probe arbitrary Spaces.

Storage Buckets

Each user should use their own private space-factory-runs Bucket. Run artifacts can include prompts, generated code, logs, traces, model IDs, endpoint schemas, and output samples.

Bucket links in the UI point to tree/runs/<run_id>/... paths. Raw run folders remain available through the Artifacts button, while the UI exposes a smaller trace/document dock for common review files.

Traces

Pi traces are stored in two forms:

• traces/raw/ — full internal trace. Treat as private.
• traces/redacted/ — best-effort redacted trace. Useful for review, but not a formal DLP guarantee.

Never assume redacted traces are safe for public release without review.

Billing and compute

The product launches Hugging Face Jobs and uses Inference Providers. Both can consume paid compute depending on the user's account, plan, quota, and selected hardware.

The app can display payment/billing readiness signals and links to HF Billing, but does not mirror live spend/quota totals. Users should review live usage in the Hugging Face Billing dashboard.

Generated Spaces

The app never publishes generated Spaces automatically. Users should review:

• generated code;
• model license and gated access requirements;
• dependency and hardware requirements;
• validation results;
• raw/redacted traces;
• any output artifacts;

before making a generated Space public.

Operational recommendations

For production or public-preview deployment:

• keep generated Spaces private by default;
• keep per-user Bucket isolation;
• monitor Job failures and cost surprises;
• periodically review redaction coverage;
• avoid broad admin tokens;
• document that automatic hardware assignment is best-effort.

Model pre-scan security boundary

The fast pre-scan is a risk heuristic, not a full sandbox audit. It reads metadata and small text/config files from the Hub without downloading weights. It can flag obvious concerns such as missing model-card guidance, custom-code indicators, unsafe weight formats, gated/private access, or unsupported tasks, but it does not prove that a model or generated Space is safe.

Treat safe as “good enough to launch the controlled build workflow”, not as a security certification.

• Repair artifacts may include log excerpts. Raw traces and repair briefs should be treated as internal unless reviewed/redacted.

Recovery and repair safety

Recovery is diagnosis-first. Pi writes REPAIR_DECISION.json before any patch is allowed, and the Factory refuses speculative code repair for empty/no-reason logs. In Strict inference mode, patch repair still runs sanity checks to prevent obvious placeholder or fake-inference substitutions. Repair, incident and blockage artifacts may contain log excerpts and should be treated as internal unless reviewed and redacted.

v120 note: Agent recovery visibility

The UI now exposes Pi diagnosis/recovery state through the Active Run Agent recovery card and links to recovery decision/blockage artifacts. This helps users understand when the Factory is waiting for HF logs, rebuilding the same code, patching, requesting hardware, or declaring a technical blocker.