RFC 0006: Secure Standard Library and Cryptography

Status: Accepted
Areas: Appendix G.7, G.12, G.18; Appendix H.8–H.13

Decision: Accepted by the project owner on 2026-10-23. This approves the design direction; implementation and conformance evidence remain outstanding.

Implementation status: Partial. The runtime exposes bounded secure_random_bytes, SHA-256, HMAC-SHA-256, PBKDF2-SHA-256, constant-time equal-length byte comparison, explicit byte zeroization, and bounded Text-to-Bytes conversion. std/crypto/password.yz provides an Argon2id password-hash wrapper using a statically linked Argon2 reference provider when configured: PHC encoding, 16-byte OS-random salts, fixed 19 MiB/t=2/p=1 work factors, 32-byte outputs, a 1024-byte password cap, bounded encoded-hash validation, verification, and rehash detection. The provider's hash algorithm is external code; YAZA does not implement cryptographic primitives. The full suite passed 32/32, and the latest password-hash test (including over-limit rejection and fresh salts) passes separately under ASan/UBSan. The macOS package was built and payload inspection confirms the static archive, header, and license are included; a program compiled and ran against the extracted provider bundle. The package remains uninstalled and contains host-added AppleDouble records. Linux provider build and runtime checks are outstanding. The pure-YAZA PostgreSQL SCRAM-SHA-256 module implements the client proof and server-signature check against the RFC 7677 vector. std/html.yz provides bounded UTF-8-validating HTML text and quoted-attribute escaping plus a conservative HTTPS/relative href helper. It does not provide rich-HTML sanitization, complete URL parsing, JavaScript/CSS contexts, safe template interpolation, or typed trusted markup. Unicode SASLprep is not implemented and non-ASCII SCRAM credentials are rejected. Automatic secret ownership/zeroization (the source Text value is not erased), AEAD, signatures, purpose-specific key types, and independent cryptographic review are absent. The full RFC acceptance criteria are not met.

Current SecretText status

std/security/secret.yz provides opaque bounded SecretText, constant redaction, explicit reveal as Option[Text], and explicit zeroization shared by aliases. The source immutable Text and environment storage are not erased; revealed values alias the managed secret buffer, while further copies made by application code remain outside the guarantee. Zeroization and reads are not synchronized for concurrent access. There is no automatic destructor, PII tracking, or full log data-flow enforcement. Normal and ASan/UBSan tests cover alias invalidation, environment values, empty and oversized inputs; a negative compile fixture confirms implicit printing is rejected.

Summary

Define safe defaults for secrets, filesystems, HTML, cryptography, authentication, and outbound network access. The standard library should make common secure operations easy and unsafe operations visible. YAZA must rely on reviewed cryptographic providers rather than implementing cryptographic algorithms itself.

Proposal

1. Add opaque Secret[T] and Pii[T] wrappers. Default formatting, debug output, JSON serialization, and log fields redact them. Explicit reveal requires a narrow scope and is audited by lint.
2. Provide cryptographically secure randomness through the operating system. Expose high-level APIs for password hashing, authenticated encryption, signatures, and key derivation using reviewed libraries and versioned safe parameter defaults.
3. Make keys purpose-specific types. Encryption keys, signing keys, password hashes, and random tokens cannot be implicitly converted. Nonces are generated/managed by the high-level API where the algorithm permits it.
4. Provide path capabilities rooted at an opened directory. Path join/resolve APIs reject traversal and symlink escape according to the selected policy; callers do not validate paths with string prefixes.
5. Provide context-aware HTML escaping and safe template output. Raw HTML insertion requires an explicit unsafe/sanitized type; escaping APIs distinguish HTML text, attributes, URLs, and JavaScript contexts.
6. Provide outbound HTTP with timeouts, redirect controls, TLS verification, size caps, and SSRF-resistant address checks as defined in RFC 0005.
7. Provide cookie/session, CSRF, password-hashing, and rate-limit building blocks with secure defaults. Application authorization remains explicit and must bind an actor to a resource/action; CORS is not authorization.
8. File, archive, XML, and regex APIs must define size, nesting, complexity, path, and timeout limits before entering the general standard library. Regex must avoid catastrophic backtracking by using a linear-time engine or explicit time/memory budgets.
9. Stdin, file reads, append, and seek operations are length-aware and bounded. Bytes APIs preserve arbitrary bytes; text APIs validate UTF-8. Path operations require an explicit root capability for sandbox-sensitive code.
10. Process execution uses an argument vector and never invokes a shell implicitly. Timeout, cancellation, environment allowlist, working directory, and stdout/stderr capture limits are explicit. Process spawning is unavailable to restricted server/WASM profiles unless granted as a capability.
11. Secure configuration loading must distinguish local .env convenience from production secret sources. Secret values are not included in access logs, panic reports, process arguments, or generated diagnostics.
12. WASM host imports and mobile/native FFI are explicit capability grants. A sandboxed target receives only declared capabilities and cannot access the host filesystem/network by default.

Non-goals

• Designing or implementing novel cryptographic primitives.
• Claiming that Secret[T] prevents memory disclosure from a compromised process.
• Treating CORS as an access-control mechanism.
• Providing automatic business authorization without application policy.

Security considerations

Cryptographic APIs are high stakes and require external review, test vectors, key-rotation guidance, and a deprecation policy. Redaction reduces accidental exposure but does not erase copies already made in memory. Path and SSRF protections must be race-resistant and tested on every target OS. Captured process output and file content can contain secrets; their default logging/debug representations must redact or omit content.

Staged implementation

1. Specify redaction behavior, path capabilities, HTML context types, and threat models.
2. Integrate reviewed OS/provider randomness and high-level cryptographic primitives; publish test vectors.
3. Add secure HTTP/cookie/password APIs, bounded process/file interfaces, and semantic lints.
4. Add archive/XML/regex interfaces only with adversarial resource-limit tests.
5. Gate WASM/mobile capabilities on sandbox and FFI review.

Implementation progress

• 2026-10-28: std/fsroot.yz adds fs_root_create_directory(root, relative_path) for bounded recursive creation under an opened directory capability. The runtime validates the complete relative path before filesystem changes and walks descriptors with O_NOFOLLOW; new directories use owner-only mode subject to umask, existing permissions are not changed, and an OS-level creation failure may leave already-created ancestors. C and public-language smoke tests cover idempotence, traversal, file/symlink components, and subsequent rooted file I/O; normal and ASan/UBSan runs pass on macOS.

• 2026-10-28: Added fs_root_list_directory(root, relative_path) to the rooted capability. It opens directories through descriptor-relative O_NOFOLLOW traversal, sorts UTF-8 names bytewise, rejects malformed/ambiguous names, and fails instead of truncating above 4,096 entries or 512 KiB of combined names. C and YAZA-language checks cover empty/root/nested listings, traversal and symlink rejection, and both caps; macOS normal and ASan/UBSan runs pass. Permission-changing APIs, broader metadata, descriptor streams, an OS sandbox, and non-macOS verification remain open.

• 2026-10-28: Added fs_root_metadata(root, relative_path) -> Result[FsMetadata, Text] for typed kind, file size, low-nine permission bits, and nanosecond modification time. It uses rooted parent resolution and fstatat with AT_SYMLINK_NOFOLLOW, allowing only regular files/directories and rejecting links/special files. Normal and ASan/UBSan C and YAZA-language checks pass on macOS; permission-changing APIs, broader metadata, streams, an OS sandbox, and non-macOS verification remain open.

• 2026-10-28: Added process_env and process_timeout_env alongside process_capture_env. All three explicit-environment variants launch with exactly the supplied entries and reject LD_*, DYLD_*, GCONV_PATH, and GLIBC_TUNABLES; supplied PATH values must contain absolute, traversal-free components. Argument and environment lists each have 256-entry, 8 KiB-per-entry, and 128 KiB aggregate-byte limits. Tests cover ambient-variable exclusion, forbidden loader variables, empty/traversal PATH components, oversized argument and environment lists, successful explicit launch, and timeout termination. Legacy process APIs still inherit the parent environment, and neither command allowlists nor an OS sandbox are implemented.

• 2026-10-26: Added SecretText and its standard-library constructors, environment lookup, fixed redaction, explicit reveal, and explicit zeroization. Normal and ASan/UBSan tests cover alias invalidation, environment values, empty and oversized inputs; a negative compile fixture confirms implicit printing is rejected.

• 2026-10-26: Added bytes_from_text_bounded(Text, Number) -> Result[Bytes, Text], which checks a maximum with a bounded scan before allocating a copy. Added password_hash_argon2id, password_verify_argon2id, and password_hash_needs_rehash using the external Argon2 provider. The wrapper fixes Argon2id v=19 at m=19456,t=2,p=1, uses OS-generated 16-byte salts and 32-byte outputs, accepts passwords up to 1024 bytes, validates the exact bounded PHC parameters before invoking verification, and wipes temporary password/salt Bytes. The full native bootstrap passed three self-host stages with identical generated C, 32/32 language tests, HTTP/API smoke, and sanitizer tests; the latest password test including fresh-salt uniqueness was rerun normally and under ASan/UBSan. The macOS package was built and its payload listing confirms the provider archive, header, and license are present; it has not been installed on a clean Mac, and the managed host adds AppleDouble records. Linux and provider update-policy verification remain open. This is not an account/session system or an independent security audit.

• 2026-10-24: Added the YAZA-authored std/html.yz context-escaping slice for HTML text and quoted attributes, plus a conservative href helper that allows HTTPS and relative URLs only. Input is limited to 64 KiB per chunk, hrefs to 2 KiB, output to 384 KiB, and malformed UTF-8 or percent encodings are rejected. This does not parse every URL form, sanitize rich HTML, encode JavaScript/CSS, or meet the RFC's full typed safe-template acceptance criterion.

Acceptance criteria

• Secret values are redacted from default formatting, logs, test failure output, and CLI diagnostics.
• Cryptographic APIs pass published vectors and independent review; no primitive is implemented ad hoc.
• Filesystem tests include traversal, symlink, race, and platform-specific path cases.
• HTML APIs prove context-specific escaping and reject unsafe interpolation by default.
• SSRF tests cover redirects, DNS rebinding, IPv4-mapped IPv6, private/link-local/metadata addresses, and alternate numeric host forms.

Open questions

• The initial provider policy is CommonCrypto on macOS and OpenSSL on Linux. A supported Linux/OpenSSL version and update policy still needs to be documented and verified in CI.
• What ownership model and zeroization guarantees can YAZA realistically provide for secret bytes?
• Which authentication/session primitives belong in the language standard library versus an official web package?

← Kembali ke semua dokumentasiVersi dan status rilis →