diff --git a/AGENTS.md b/AGENTS.md index c10e10b1f..6f747c38e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -19,7 +19,21 @@ For every change: 7. inspect review feedback and exact-head checks; 8. merge only when repository policy is satisfied. -Do not bypass required checks, independent approval, or branch protection. Waiting checks are not permission to weaken tests; continue with independent product analysis or a non-conflicting next task. +Do not bypass required checks, branch protection, or any review authority actually required by current GitHub rules or an explicit operationally satisfiable OriginWeave/CWL governance rule. Waiting checks are not permission to weaken tests; continue with a non-conflicting next task. + +## Work-conserving autonomous maintenance + +**A completed action is an intermediate state**, not an implicit end of a maintenance invocation. “One bounded slice” means **one write-active slice at a time**, not one slice, pull request, RCA, check, review request, documentation update, or merge per run. + +After every completed mutation, validation result, merge, defer decision, or newly proven blocker, return to the fresh executable queue. A pending check, reviewer delay, rate limit, unavailable provider, external dependency, or writer conflict **blocks only that item** or branch. Continue with another safe, non-conflicting OriginWeave task while practical run budget remains. + +### Mandatory exit sweep + +Before autonomous maintenance ends, refetch protected `main`, every open OriginWeave pull request and issue, current reviews/checks, release state, documentation graph, and buyer-visible product gaps. Evaluate whether any safe action remains, including merge, test-first defect repair, thread resolution, duplicate cleanup, another PR/issue, protected-main acceptance, documentation repair, product-gap implementation, quality/security/operability improvement, or release evidence work. + +If any safe executable item remains, **termination is prohibited**: execute the highest-value item and repeat the sweep. End only when the practical invocation budget is exhausted or every remaining item is genuinely non-actionable under current authority, dependency order, writer lease, and safety constraints. + +Do not repeatedly poll an unchanged pending item. Defer it by exact PR/head/run/review identity, work elsewhere, and revisit after a material state change, another substantive action, or the exit sweep. ## Blocker RCA and corrective-action feasibility @@ -33,7 +47,13 @@ For every failed check, review, approval, permission, tool, infrastructure, or w 6. If the action does not produce that state transition, incorporate the evidence into the RCA and evaluate the next safe candidate; do not repeat an unsupported or disproven action. 7. Only report an external blocker after current evidence proves that no safe feasible corrective action is available. Continue one non-conflicting bounded task when the writer lease and dependency graph permit it. -A qualifying approval is a formal `APPROVED` review by an eligible non-author repository collaborator on the exact unchanged head. Comments, statuses, mentions, clean-review prose, author reviews, and unavailable bot identities are not approval. If no eligible reviewer exists, classify the condition as a reviewer-provisioning gap rather than approval latency; never synthesize, self-submit, or bypass approval. +### Review-governance realism + +A formal non-author approval is a merge gate only when **current GitHub rules** or an explicit current, operationally satisfiable OriginWeave/CWL governance rule requires it. Advisory comments, statuses, automated-review prose, author reviews, and unavailable identities never substitute for a counted approval when one is actually required. + +When current rules require counted approval, the required evidence must be a formal `APPROVED` review by an eligible non-author **repository collaborator** (or another identity that current GitHub policy explicitly counts). If that governing rule remains active but no legitimate eligible path exists, classify the condition as a **reviewer-provisioning gap**; never synthesize, self-submit, or impersonate approval. + +The organization currently documents a **solo-maintainer** governance condition. When there are **fewer than two eligible** independent maintainers, an otherwise impossible non-author approval rule is **on hold** rather than manufactured or bypassed; exact-head CI, security, 100% coverage, rustdoc, resolved findings, live-base checks, and branch protection remain mandatory. The independent-review gate must be **re-enabled** when the repository again has two or more eligible maintainers or when current GitHub rules independently require it. If a counted reviewer route is required, verify collaborator/team/App eligibility before requesting it and never repeat a route already proven ineligible without a relevant state change. ## Architecture constraints @@ -95,4 +115,4 @@ A skipped security, GPU, browser, TLS, or statistical test is not passing eviden ## Release contract -A release requires all current-head checks, complete coverage and docs, updated `CHANGELOG.md`, SBOM and provenance, reproducible artifacts, compatibility evidence, security review, and an explicit version decision. Pre-alpha commits are not releases. \ No newline at end of file +A release requires all current-head checks, complete coverage and docs, updated `CHANGELOG.md`, SBOM and provenance, reproducible artifacts, compatibility evidence, security review, and an explicit version decision. Pre-alpha commits are not releases. diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index df87f05d3..9b23ef9f0 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -1,5 +1,20 @@ # OriginWeave Architecture +## Authoritative documentation graph + +This file is the canonical product-wide topology and bounded-context view. It is intentionally linked to the rest of the authoritative documentation graph so a maintainer or buyer does not have to reconstruct requirements or decisions from chat, pull-request prose, or isolated feature plans: + +- [Product requirements](docs/PRD.md) +- [Technical requirements and implementation-status boundaries](docs/TRD.md) +- [Architecture decision index and lifecycle](docs/adr/README.md) +- [UML and control-flow diagrams](docs/uml/README.md) +- [Conceptual ERD and durable domain model](docs/erd/README.md) +- [Requirement, decision, standards, and implementation traceability](docs/traceability/README.md) +- [Research and standards doctoring](docs/doctoring.md) +- [Product roadmap](docs/product-roadmap.md) + +Protected-main code and executable tests define current implementation truth; deployed build/release artifacts, migrations, and configuration are additional operational evidence when they exist. Accepted ADRs define design authority, not proof that planned behavior has shipped. The PRD/TRD/diagrams may also contain `Planned`, `Proposed`, or `Open` product direction; those labels must remain explicit until corresponding implementation and review evidence reaches protected `main`. + ## 1. Product definition OriginWeave is an enterprise agentic web runtime and provenance-native browser control plane. Chromium remains the compatibility kernel; Rust owns new governance, destination, direct network, TLS identity, resource, evidence, and agent-facing contracts. This separation minimizes the Chromium patch surface and allows the same Rust modules to operate in a desktop browser, headless service, naruon module, or external agent runtime. @@ -7,7 +22,7 @@ OriginWeave is an enterprise agentic web runtime and provenance-native browser c ## 2. Architectural principles 1. **Compatibility before reinvention.** Blink, V8, Skia, Viz, Dawn, Site Isolation, sandboxing, and Manifest V3 remain upstream-compatible. -2. **Authority is explicit.** No ambient browser state or page content implicitly grants a capability; observed node authority is bound to an exact browser session, browsing context, canonical origin, and document epoch. +2. **Authority is explicit.** No ambient browser state or page content implicitly grants a capability. 3. **Actions are typed.** Production agents do not receive unrestricted JavaScript evaluation as a default tool. 4. **Observe before acting; verify after acting.** A command is successful only when its expected post-condition is observed. 5. **Secrets stay outside model context.** Models receive opaque handles; a broker resolves values directly into a trusted browser process. @@ -55,7 +70,6 @@ An Agent Task session must not automatically share the default human profile. Fu Owns stable value contracts without I/O: - browser-equivalent normalized `Origin` values that reject ambiguous numeric hosts; -- nonzero `BrowserSessionId`, `BrowsingContextId`, and `DocumentEpoch` identities plus `ObservedNodeHandle` values bound to their exact session, context, origin, document lifetime, and adapter-local node identifier; - immutable `ActionIntentDigest` values; - `SessionMode` and `ExecutionPurpose`; - `InstructionSource` and `SecretDelivery`; @@ -152,7 +166,7 @@ Observation should prefer the most structured trustworthy source available: 4. accessibility tree combined with DOM and layout; 5. screenshot or vision fallback for canvas and inaccessible custom interfaces. -Raw HTML is not the default model input. Full snapshots are followed by incremental semantic diffs, versioned by document epoch. Every actionable node reference carries its nonzero browser-session identity, browsing-context identity, canonical origin, document epoch, and adapter-local node identifier. A browser adapter must validate all five values immediately before use; another automation session, navigation, document replacement, origin change, or a different tab or frame context invalidates the handle. +Raw HTML is not the default model input. Full snapshots are followed by incremental semantic diffs, versioned by document epoch. Node references become invalid after navigation or epoch change. ## 8. Action lifecycle @@ -163,7 +177,6 @@ user intent → typed request → instruction-source check → capability and browser-equivalent origin check -→ browser-session + browsing-context + origin + document-epoch node binding → resolved-destination approval and pinning → exact direct TCP peer binding → authenticated TLS service identity @@ -248,7 +261,6 @@ WARC stores source exchanges and resources; relational storage holds sessions, p - Browser content is data, never authority. - Secrets are never included in model prompts, traces, or provenance values. - Generic header and query values are never retained by the evidence kernel. -- Observed node handles are valid only in the exact browser session, browsing context, canonical origin, and document epoch that produced them; adapter-local node identifiers alone never confer authority. - Logical origin grants, resolved-destination grants, actual peer evidence, and TLS service identity remain distinct. - DNS answer expansion after approval is denied as a possible rebinding event. - Direct TCP accepts only a canonical approved socket, never a hostname. @@ -283,7 +295,7 @@ No deployment mode may depend on an in-process singleton. Session, policy, desti | Attribute | Required evidence | |---|---| | correctness | contract, property, hostile-input, real TCP/TLS, and post-condition tests | -| safety | prompt-injection, secret, session/context-bound node, origin, destination, rebinding, redirect, exact-peer, TLS identity, approval, and renderer-boundary tests | +| safety | prompt-injection, secret, origin, destination, rebinding, redirect, exact-peer, TLS identity, approval, and renderer-boundary tests | | reliability | crash recovery, checkpoint, retry, timeout, and idempotency tests | | performance | input latency, frame time, task RSS, VRAM, transfer, connection, handshake, and token metrics | | interoperability | BiDi/CDP/MCP/WARC/PROV and Manifest V3 compatibility suites | @@ -292,4 +304,4 @@ No deployment mode may depend on an in-process singleton. Session, policy, desti ## 15. Change control -Changes to the compatibility-kernel boundary, risk taxonomy, secret model, origin model, session/context-bound node-handle identity, canonical intent model, evidence semantics, destination taxonomy, DNS pinning semantics, direct socket authority, TLS reference identity, trust-root semantics, trusted-time semantics, ALPN policy, redirect policy, resource mitigation semantics, or protocol versioning require a new ADR. The current baseline decisions are recorded under `docs/adr/`. \ No newline at end of file +Changes to the compatibility-kernel boundary, risk taxonomy, secret model, origin model, canonical intent model, evidence semantics, destination taxonomy, DNS pinning semantics, direct socket authority, TLS reference identity, trust-root semantics, trusted-time semantics, ALPN policy, redirect policy, resource mitigation semantics, or protocol versioning require a new ADR. The current baseline decisions are recorded under `docs/adr/`. diff --git a/CHANGELOG.md b/CHANGELOG.md index c6ccce4ca..6e4bd39ca 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,62 +10,53 @@ All notable changes to OriginWeave are documented in this file. The format follo - Canonical HTTPS and loopback-origin boundary with case-normalized schemes and hosts, default-port normalization, IPv4/IPv6 handling, browser-special numeric-host rejection, and explicit malformed-input errors. - Typed browser actions, capabilities, risk classes, execution modes, robots decisions, secret-delivery contracts, immutable canonical action-intent digests, and intent-bound approval scopes. - Deterministic fail-closed policy evaluation for untrusted instructions, origin grants, crawler restrictions, execution-mode and purpose consistency, approvals, and brokered secrets. -- Purpose-bound sensitive-data policy that carries no protected value bytes, binds disclosure to exact tenant, task, field, purpose, canonical destination, and classification authority, constrains tenant/task/field/purpose identifiers to 1–128 byte ASCII policy tokens, preserves seven explicit disclosure outcomes, and evaluates opaque-handle admission against that same classification-bound destination scope plus exclusive expiry and maximum use count. -- Session- and context-bound node authority with nonzero browser-session, browsing-context, and document-epoch identities, adapter-local node identifiers, exact canonical-origin binding, and deterministic cross-session, cross-context, cross-origin, and stale-epoch rejection before a future browser adapter acts on an observed node. - Fail-closed resolved-destination policy with IPv4/IPv6 special-purpose and reviewed cloud-platform endpoint classification, IPv4-mapped canonicalization, explicit class grants, non-empty origin-bound DNS snapshots capped at 256 resolver addresses, concrete connection pinning, DNS-set expansion detection, and per-hop redirect reauthorization. -- Explicit bounded proxy/PAC route authority in `originweave-destination`: direct-only by default, separately allow-listed Chromium-compatible proxy server identifiers and PAC source origins, independent authorization for PAC-selected DIRECT versus proxy routes, exact canonical target/proxy/PAC evidence, and no DNS, socket, PAC execution, CONNECT, authentication, or Chromium side effects. - Direct-only `originweave-network` TCP boundary with explicit canonical `SocketAddr` authority, zero IPv6 flow and scope metadata unless separately modeled, a non-cloneable single-use plan, a 30-second per-attempt timeout ceiling, at most four attempts, exact `peer_addr` verification before stream exposure, and no hostname re-resolution or ambient proxy inheritance. - Authenticated `originweave-tls` service-identity boundary that consumes an existing verified TCP stream, requires exact TLS-origin and transport-origin equality, derives RFC 9525 DNS or literal-IP reference identity only from the canonical HTTPS origin, validates WebPKI with explicit roots and fixed time, permits only TLS 1.2 and TLS 1.3, and never reconnects or resolves. -- Bounded TLS policy for total handshake time, ALPN identifiers, trust-root count and bytes, server-presented certificate count and bytes, and a caller-selected minimum leaf-certificate validity horizon capped at seven days, with explicit optional-versus-required ALPN behavior and `NotConfigured` revocation evidence. -- Policy-enforced TLS leaf-certificate validity horizon that layers a fail-closed delegated-task safety budget on authenticated fixed-time evidence, defaults to zero for compatibility, conservatively rounds fractional durations, rejects excessive configured horizons before network execution, and withholds the authenticated stream when the verified leaf expires before the configured task horizon while keeping the product policy distinct from RFC 5280 point-in-time validity semantics. +- Bounded TLS policy for total handshake time, ALPN identifiers, trust-root count and bytes, and server-presented certificate count and bytes, with explicit optional-versus-required ALPN behavior and `NotConfigured` revocation evidence. - Credential-free TLS evidence containing canonical origin, requested and observed peer, DNS/IP reference identity, TLS version, cipher-suite identifier, selected ALPN or explicit absence, leaf certificate and SPKI hashes, server-presented certificate hashes and bounds, trust-bundle identity and hash, validity interval, fixed verification time, revocation configuration, and measured handshake duration. - Credential-free connection and redirect evidence containing canonical addresses, destination classes, target digests, hop numbers, and approved-address counts. - Credential-free verified TCP evidence containing the logical origin, requested socket, observed peer, destination class, successful attempt number, and per-attempt timeout. -- Purpose-bound sensitive-access evidence receipts that retain bounded tenant, actor, task, protected-field identifiers, purpose, canonical destination, classification, outcome, policy version, approval reference, and lifecycle times without retaining protected field values or opaque-handle payloads. - Standard `Display` and `std::error::Error` contracts for destination, redirect, digest, direct-network, and TLS failures, including preserved destination-policy, rustls, and operating-system sources where applicable. - Real loopback TCP integration proof plus deterministic timeout, refusal, retry, peer-inspection, peer-mismatch, canonicalization, IPv6 metadata, and single-use replay tests. -- Real loopback rustls integration covering trusted DNS SAN, Common-Name fallback rejection, wrong-name and untrusted-root rejection, fixed-time expiry and not-yet-valid failures, exact IPv4 and IPv6 SANs, TLS 1.2/TLS 1.3, required and optional ALPN, transport-origin binding, and a point-in-time-valid certificate rejected before stream exposure when its remaining validity is shorter than the configured delegated-task horizon. +- Real loopback rustls integration covering trusted DNS SAN, Common-Name fallback rejection, wrong-name and untrusted-root rejection, fixed-time expiry and not-yet-valid failures, exact IPv4 and IPv6 SANs, TLS 1.2/TLS 1.3, required and optional ALPN, and transport-origin binding. - Cumulative interactive-first RAM, VRAM, batch, local-model, admission, pause, and compositor-pressure mitigation plans, including active-consumer reduction at exact hard limits. - Universally value-redacted network evidence with explicit path, metadata, and provenance bounds; ambiguous path rejection; validated source URLs; lowercase SHA-256 identifiers; and verification state. - Rust 1.97.1 build contract, strict Clippy and rustdoc gates, and exact production function, line, region, and branch coverage enforcement. - Hourly bounded OpenCode product-development workflow using `NVIDIA_NIM_API_KEY`, an unprivileged disposable workspace, loopback-only model broker, independently verified patches, and publication through a dedicated `OPENCODE_PR_TOKEN` that cannot review or merge. -- Architecture, agent, security, contribution, research, database naming, roadmap, quality-gate, TLS service-identity, session/context node-authority, purpose-bound sensitive-data, and hourly agent credential-boundary ADR documentation. +- Architecture, agent, security, contribution, research, database naming, roadmap, quality-gate, and TLS service-identity ADR documentation. +- Authoritative product documentation graph spanning PRD, TRD, ADR lifecycle/index, product-wide UML, conceptual ERD, requirement/decision traceability, threat modeling, product-wide test strategy, operability, API/protocol, release/rollback, and current primary-source standards doctoring, with machine-checkable repository contracts that keep conversation-derived future work distinct from protected-main implementation claims. +- Purpose-bound data-governance and privacy baseline that rejects both blanket masking and ambient raw-value propagation, defines field-scoped just-in-time disclosure, opaque-handle/trusted-broker boundaries, model/provider/region policy, retention/deletion/residency/break-glass controls, truthful CSAP/SOC 2 readiness language, and machine-checkable documentation contracts without inventing an OriginWeave-owned production database. +- Proposed product-wide target-architecture ADRs for the Rust control plane, isolated execution modes, typed actions, semantic observation/stale-node authority, prompt-injection and secret separation, resource-governor priority, provenance evidence, browser/protocol adapters, crawler policy, and hourly automation operational closure; these remain Proposed rather than shipped claims until protected review and merge. ### Changed - Separated logical origin authority from resolved network destination authority; an origin grant no longer implies permission to connect to every resolver result. -- Separated proxy-server routing identity from web-origin identity: HTTP, HTTPS, SOCKS4, SOCKS5, and QUIC proxy schemes retain their own canonical authority, so an ordinary remote HTTP proxy is representable without weakening the web-origin HTTPS requirement. - Separated resolved-address authorization from direct transport evidence; an approved IP now becomes a usable stream only after the operating system reports the exact requested IP and port. - Separated exact TCP peer proof from authenticated TLS service identity; an observed peer becomes an authenticated HTTPS stream only after explicit-root, fixed-time, SAN-bound WebPKI verification over that same stream. -- Separated sensitive-data disclosure from network, session, repository, administrator, and model-credential authority; later storage, broker, model-disclosure, evidence, and lifecycle modules must consume explicit field-level policy instead of inferring raw-value access. -- Restricted direct TCP retries to an explicit transient operating-system error allow-list; deterministic permission, input, and local-address failures now stop after the first attempt while retaining the original error source. - Replaced single resource-pressure directives with a cumulative mitigation plan so simultaneous RAM, VRAM, frame, model, and admission pressure cannot discard required actions. - Changed generic network capture from finite deny-lists or safe-name allow-lists to unconditional value redaction. Typed metadata values and bodies now require a separate schema-specific capture contract. -- Updated the first Chromium slice to distinguish implemented origin, destination, direct TCP, TLS identity, node-authority, and sensitive-data policy kernels from the remaining trusted DNS adapter, proxy/PAC execution, HTTP budget, MIME, download, trusted sensitive-value broker, and Chromium integration required before safe navigation and protected-value disclosure can be claimed. -- Separated hourly product PR publication authority from the organization review and merge system, added live default-branch and release-blocker rechecks immediately before publication, exhaustively paginate release-blocker results in bounded 100-item API pages before filtering pull-request entries so labeled PRs cannot mask a real blocking issue on any later page, and made a missing dedicated `OPENCODE_PR_TOKEN` fail closed after a verified change instead of producing a green publication no-op. +- Updated the first Chromium slice to distinguish implemented origin, destination, direct TCP, and TLS identity kernels from the remaining trusted DNS adapter, proxy/PAC, HTTP budget, MIME, download, and Chromium integration required before safe navigation can be claimed. +- Separated hourly product PR publication authority from the organization review and merge system, and added live default-branch and release-blocker rechecks immediately before publication. +- Made the agent-development contract work-conserving: completing one bounded slice, RCA, review request, check, merge, or documentation change is an intermediate state; maintenance must return to the live queue, treat waits as item-local, and perform a mandatory exit sweep before terminating while executable OriginWeave work remains. - Moved autonomous-agent Cargo targets and Python bytecode caches outside the proposed source tree and prefetched locked Cargo dependencies for offline verification. -- Split deterministic open-PR, release-blocker, and dry-run evaluation from the conditional NVIDIA credential step so stopped runs never receive `NVIDIA_NIM_API_KEY`; made a missing `NVIDIA_NIM_API_KEY` fail closed after deterministic governance selects the model-backed path instead of silently skipping all remaining work with a green result; replaced post-model raw-key rematerialization with a runner-only length, SHA-256, and rolling-hash fingerprint used solely for exact leak detection; bounded untrusted `PR_MESSAGE.md` before byte-wise leak scanning; stat-size-check model-controlled workspace files against the one-mebibyte per-file bound before any full byte comparison used to discover changed files; added an evidence-first RCA, feasibility, materially distinct corrective-action, and exact-command revalidation contract; reset every fallback model to the pristine source tree; classified model timeouts, model or tool failures, and credential-broker failures before retry; emitted bounded broker diagnostics when broker failure makes retry infeasible; made final cleanup use the privilege required for the UID-65532-owned model configuration; and expanded the job budget to 180 minutes so all three advertised 35-minute model attempts plus independent verification can actually execute without weakening fail-closed egress. -- Distinguished loopback broker liveness from NVIDIA provider viability: the trusted broker now exposes credential-free request-generation counters for upstream `401`/`403` authentication or authorization rejection and `429` rate limiting, cross-model fallback stops when current-attempt evidence proves either condition, and every pre/post-attempt `/statusz` read is locally schema-validated. Missing or malformed broker telemetry now records `credential_broker_unavailable`, emits bounded diagnostics, and prevents a model from starting instead of escaping the RCA path through shell `errexit`. Generation binding prevents late predecessor responses from poisoning a later pristine attempt, while transient rate limiting is retried only by a later fresh scheduled invocation rather than by consuming another same-provider model slot in the finite run. -- Updated research doctoring to pin Chromium canonicalizer evidence to an immutable revision, add RFC 9293, RFC 5280, RFC 8446, RFC 9525, rustls 0.23.42, Rust `TcpStream`, WebDriver, and WebDriver BiDi evidence, distinguish the April 2026 Fugu beta from the June 2026 release, and treat vendor benchmark claims as first-party evidence rather than independent validation. +- Updated research doctoring to pin Chromium canonicalizer evidence to an immutable revision, add RFC 9293, RFC 5280, RFC 8446, RFC 9525, rustls 0.23.42, and Rust `TcpStream` evidence, distinguish the April 2026 Fugu beta from the June 2026 release, and treat vendor benchmark claims as first-party evidence rather than independent validation. ### Security - Raw page content cannot become a trusted instruction. - Raw secrets are rejected and secret-capable actions require an opaque broker handle. -- Sensitive-data policy denies disclosure when tenant, task, field, business purpose, canonical destination, or classification differs from the explicit scope; malformed, oversized, whitespace-bearing, control-bearing, or non-ASCII authority identifiers also fail closed even when both sides match. Opaque-handle evaluation fails closed on the same bounded destination and classification scope, including field reclassification, expiry, or exhausted use count, and the first authority API contains no protected value bytes. Later broker/service adapters must consume this same scope and atomically enforce authoritative use state before value resolution. - Crawler mode is read-only, must pair with the public-crawl purpose, and fails closed without an applicable robots-policy decision. - State-changing actions are same-origin by default. - R3 and R4 approvals are bound to the exact action, target origin, and immutable digest of the complete canonical action intent; R5 legal consent is non-delegable. -- Observed node handles cannot be reused across browser sessions or browsing contexts, or after the canonical origin or document epoch changes, preventing stale or colliding adapter-local node identifiers from silently crossing an isolated profile, task, tab, frame, navigation, or document boundary. - Shortened, integer, hexadecimal, and legacy octal-looking IPv4 host spellings are rejected so the policy origin cannot diverge from Chromium host interpretation. - IPv4-mapped IPv6 is canonicalized before destination classification and pin comparison so mapped private or loopback addresses cannot bypass IPv4 policy. - The default destination policy permits only public addresses and denies unspecified, loopback, private, shared, link-local, metadata, documentation, benchmarking, multicast, broadcast, transition, and protocol-reserved destinations. -- Azure platform IP `168.63.129.16` and Amazon EKS Pod Identity endpoints `169.254.170.23` and `fd00:ec2::23` are classified as metadata or platform services before broader address-range rules. +- Azure platform IP `168.63.129.16` and Amazon EKS Pod Identity endpoints `169.254.170.23` and `fd00:ec2::23` are classified as metadata or platform services before broader public, link-local, or unique-local rules. - Resolver answers are rejected when empty or larger than 256 addresses, preventing an unbounded resolver response from entering policy state. - `localhost` may approve only loopback addresses, while literal IPv4 and IPv6 origins may approve only the exact canonical address encoded in the origin. - Resolver answers must remain a non-empty subset of the origin-bound approved address set; any newly introduced address fails closed as a possible DNS-rebinding event. - Every redirect rechecks target-origin authority, target-bound resolution, HTTPS downgrade, complete-target cycle state, and hop capacity before policy state changes. -- Proxy route policy permits only exact canonical server identities and PAC source origins; route approval does not grant destination, TCP peer, proxy authentication, CONNECT, TLS, or final-target authority. - Direct TCP plans reject port zero, zero or excessive timeouts, excessive attempts, unapproved IPs, non-canonical IPv4-mapped IPv6 sockets, and IPv6 flow or scope metadata not represented in destination authority before connection I/O. - Direct connection code accepts only an explicit `SocketAddr`, never a hostname, and does not read proxy environment variables. - Established streams are discarded when peer inspection fails or the observed remote IP or port differs from the approved socket. @@ -75,7 +66,6 @@ All notable changes to OriginWeave are documented in this file. The format follo - TLS resumption, 0-RTT, secret extraction, key logging, client certificates, certificate compression, and dangerous custom verifier hooks are disabled in the first slice. - The operating-system peer is rechecked before, during, and after the deadline-bound TLS handshake. - ALPN selection is restricted to the caller's bounded allow-list, while absence is either explicitly recorded or rejected by policy. -- A configured nonzero TLS task horizon is enforced only after normal WebPKI success and before the authenticated stream is exposed; a leaf certificate that expires too soon fails with credential-free duration evidence, and horizons beyond the seven-day product maximum are rejected before network execution. - Revocation is reported as not configured; the product makes no OCSP or CRL validation claim without supplied revocation evidence. - Every generic network header and query value is redacted before evidence leaves the trusted boundary, including conventionally benign field names containing attacker-controlled bytes. - Evidence capture enforces count and byte bounds and rejects credential-bearing source URLs, query strings, fragments, controls, whitespace, malformed percent escapes, encoded separators, dot segments, and backslash paths. diff --git a/SECURITY.md b/SECURITY.md index 257ddbf66..49defbfb8 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,5 +1,7 @@ # Security Policy +The product-wide trust zones, assets, attacker scenarios, mitigations, acceptance evidence, and residual risks are defined in [`docs/THREAT_MODEL.md`](docs/THREAT_MODEL.md). This policy defines reporting and top-level invariants; the threat model does not replace coordinated disclosure or make a certification claim. + ## Supported versions OriginWeave is pre-alpha and has no supported production release. Security fixes are applied to the default branch. Do not deploy the current repository as an unattended production browser. diff --git a/docs/API_CONTRACT.md b/docs/API_CONTRACT.md new file mode 100644 index 000000000..f750922fd --- /dev/null +++ b/docs/API_CONTRACT.md @@ -0,0 +1,385 @@ +# OriginWeave API and Protocol Contract + +- **Status:** Proposed product-wide API baseline +- **Product status:** Pre-alpha; no public compatibility guarantee yet +- **Technical requirements:** [`TRD.md`](TRD.md) +- **Conceptual model:** [`erd/README.md`](erd/README.md) +- **Threat model:** [`THREAT_MODEL.md`](THREAT_MODEL.md) + +## 1. Purpose + +OriginWeave needs one stable authority model even though different deployments may use Chromium internals, WebDriver BiDi, Chrome DevTools Protocol, WebMCP, MCP, desktop IPC or an embedded Rust API. This document defines the direction of the **OriginWeave Protocol** and the rules every public/internal adapter must preserve. + +This is a contract baseline, not a claim that the complete network service or SDK is implemented on protected `main`. + +## 2. Protocol design goals + +- transport-neutral; +- versioned and schema-first; +- tenant/task/session scoped; +- opaque identifiers rather than raw browser/process pointers; +- deterministic authority validation outside model output; +- explicit deadlines, cancellation and idempotency; +- bounded request/response sizes; +- typed errors and degraded states; +- evidence identifiers returned separately from sensitive values; +- state-changing success tied to an observed **post-condition**; +- adapter-specific identifiers translated through scoped registries. + +## 3. Non-goals + +The protocol does not: + +- expose arbitrary JavaScript as the standard action interface; +- expose browser cookies/passwords/API keys to the caller/model; +- make CDP/WebDriver IDs durable OriginWeave IDs; +- accept raw page text as policy; +- collapse origin/destination/route/TCP/TLS/HTTP authority into one URL field; +- treat protocol authentication alone as task authorization; +- guarantee every future Chromium/CDP/WebMCP feature. + +## 4. Versioning + +Before 1.0, every serialized contract carries a protocol version such as: + +```json +{ + "protocol_version": "originweave/0.1" +} +``` + +Compatibility policy before 1.0: + +- additive compatible fields may appear behind explicit version/capability negotiation; +- removing/renaming/reinterpreting an existing field requires a version change; +- security semantics never become permissive merely for backward compatibility; +- adapters reject unknown mandatory capability/version combinations; +- supported WebDriver/CDP/WebMCP/MCP versions are documented independently from the OriginWeave protocol version. + +## 5. Identity vocabulary + +Planned external wire objects use descriptive identifiers such as: + +```text +tenant_record_id +agent_session_id +browser_profile_id +browsing_context_id +page_snapshot_id +semantic_node_id +action_intent_id +policy_decision_id +action_event_id +postcondition_evidence_id +provenance_record_id +secret_handle_id +``` + +These values are **opaque**. Clients must not infer ordering, ownership, browser process, database placement or authority from their syntax. + +External adapter IDs such as CDP `backendNodeId`, WebDriver element references or browser process IDs are never accepted as global authority by themselves. + +## 6. Common envelope + +A request that can mutate or access tenant-scoped state includes an authenticated transport/session plus a logical envelope similar to: + +```json +{ + "protocol_version": "originweave/0.1", + "tenant_record_id": "opaque", + "agent_session_id": "opaque", + "request_id": "opaque", + "idempotency_key": "opaque", + "deadline_at": "2026-08-09T10:00:00Z" +} +``` + +The transport authenticates the caller/workload. The envelope scopes the operation. Neither alone grants an action capability. + +## 7. Idempotency + +Every externally replayable state-changing command defines explicit **idempotency** behavior. + +Rules: + +- idempotency keys are scoped by tenant, session, operation kind and semantic request contract; +- a reused key with different semantic content fails deterministically; +- an idempotency record does not authorize the operation; policy is still revalidated as required; +- retries after ambiguous external side effects may return `quarantined`/reconciliation-required rather than re-execute; +- idempotency retention is bounded and declared; +- secret-handle max-use semantics remain independent of request idempotency. + +## 8. Deadline and cancellation + +Requests use one end-to-end deadline. Lower layers consume the remaining budget rather than reset a fresh unlimited timeout. + +Cancellation distinguishes: + +- cancellation before any external side effect; +- cancellation while outcome is known not to have committed; +- cancellation after a side effect may have committed; +- local browser/model/network cancellation completion; +- task state requiring quarantine/reconciliation. + +## 9. Capability negotiation + +A session exposes a bounded capability document, for example: + +```json +{ + "supported_operations": [ + "browser.navigate", + "browser.observe", + "browser.query", + "browser.act", + "browser.extract", + "browser.checkpoint" + ], + "observation_channels": [ + "structured_data", + "accessibility_dom_layout" + ], + "adapter_profiles": { + "webdriver_bidi": "planned", + "cdp": "planned", + "webmcp": "experimental_optional" + } +} +``` + +Supported operation does not mean the current task is authorized to use it. Per-task policy/capability/origin/risk checks remain separate. + +## 10. Session operations + +Planned high-level surface: + +### `browser.create_session` + +Inputs: + +- requested execution mode; +- execution purpose; +- profile/isolation request; +- resource-budget profile; +- allowed policy profile reference. + +Outputs: + +- `agent_session_id`; +- effective execution mode/purpose; +- profile isolation class; +- supported capability metadata; +- session evidence reference. + +Does not return raw profile/cookie state. + +### `browser.close_session` + +Closes or begins closing browser contexts, revokes task-scoped handles/approvals according to policy and finalizes evidence. Closing a session does not erase audit evidence whose retention is separately governed. + +## 11. Navigation operations + +### `browser.navigate` + +Accepts a canonical target contract, not ambient browser URL mutation. + +Preconditions include: + +- session/mode/purpose valid; +- navigation capability; +- canonical origin authority; +- destination/route/network/TLS/HTTP authority through the actual adapter path; +- deadline/resource admission. + +Output includes resulting browsing context/document authority and evidence references. Redirects follow the independently governed chain; one approved origin does not grant every redirect. + +### `browser.go_back` + +Requires current context validity and returns a new/updated document epoch when navigation changes the actionable document. + +## 12. Observation operations + +### `browser.observe` + +Request selects bounded channels/fields, for example: + +```json +{ + "observation_request": { + "channels": ["structured", "accessibility", "dom", "layout"], + "maximum_nodes": 2000, + "maximum_text_bytes": 262144 + } +} +``` + +Output is a `page_snapshot` plus typed `semantic_node` records and source/evidence references. Sensitive values are excluded or represented by separately authorized handles/derived values. + +### `browser.observe_changes` + +Returns incremental changes after a known snapshot/epoch. If the underlying actionable document changed incompatibly, returns an explicit stale/epoch-changed result rather than attempting to merge incompatible snapshots. + +## 13. Query operations + +### `browser.query` + +Queries the OriginWeave semantic observation contract; callers do not need to synthesize unrestricted CSS/XPath/JavaScript. + +Query predicates may include role, accessible name, state, structured field, source channel and scoped layout attributes. Results contain opaque semantic-node handles bound to the current session/context/origin/document epoch. + +## 14. Action operations + +### `browser.act` + +Request is a typed action intent, conceptually: + +```json +{ + "action_kind": "click_node", + "semantic_node_id": "opaque", + "expected_origin": "https://example.com", + "risk_class": "R2", + "post_condition": { + "kind": "dialog_visible", + "timeout_ms": 5000 + } +} +``` + +The caller/model cannot self-authorize `risk_class`, capability or approval simply by setting fields; the deterministic control plane computes/revalidates effective policy. + +Immediately before dispatch, the runtime revalidates: + +- session/context/document/node authority; +- task capability and purpose; +- origin/destination/secret scope as relevant; +- exact approval evidence where required; +- resource/deadline state. + +Success response is not produced until the declared/derived **post-condition** is observed. Outcomes include `succeeded`, `failed`, `timed_out`, `cancelled`, `quarantined` and typed policy/stale errors. + +## 15. Secret/sensitive operations + +### `browser.fill_secret` + +The caller supplies an `secret_handle_id` or other approved sensitive handle, never the raw value. The trusted broker rechecks audience, tenant, task, field, purpose, origin, expiry, revocation, max uses and approval before filling through a trusted adapter. + +The response contains only access/evidence metadata and post-condition state. + +### `sensitive.resolve_derived` + +Where policy permits, a caller may request a derived safe representation rather than the original value. The derivation and retention policy are typed and versioned; no generic “unmask” method exists. + +## 16. Extraction operations + +### `browser.extract` + +Inputs: + +- versioned extraction schema; +- allowed source channels; +- field-level evidence requirements; +- bounded record/byte limits. + +Outputs: + +- typed values; +- verification state/confidence where applicable; +- source/evidence identifiers; +- model/provider/prompt provenance when interpretation was needed. + +A value without the required evidence is omitted, rejected or explicitly marked unsupported according to the schema contract; it is not silently promoted to verified. + +## 17. Download operations + +### `browser.download` + +Requires action/destination/resource policy and returns a `download_artifact_id` plus digest/MIME/source evidence. Filenames are metadata only until a persistence adapter sanitizes and authorizes a destination. Content is not executed by the protocol layer. + +## 18. Checkpoint and recovery operations + +### `browser.checkpoint` + +Creates a bounded recoverable task/browser checkpoint where the adapter supports it. The response identifies what state is persisted and what external side effects are not replayable. + +### `browser.reconcile` + +Planned operator/runtime operation for quarantined tasks. It compares external authoritative state with OriginWeave evidence before an action can be compensated, retried or manually completed. + +## 19. Evidence operations + +### `evidence.get` + +Returns a caller-authorized typed evidence record. Sensitive generic fields remain redacted. Evidence access itself is tenant/policy scoped. + +### `evidence.export` + +Produces a versioned evidence/provenance bundle under export/retention policy. WARC/PROV/JSON/other encodings are adapters to the logical evidence model. + +## 20. Error model + +Wire errors have stable machine codes and safe human messages, for example: + +```json +{ + "error": { + "code": "stale_document_epoch", + "message": "The observed node no longer belongs to the current document.", + "retryable": false, + "evidence_id": "opaque" + } +} +``` + +Properties: + +- no raw credentials/protected bodies; +- deterministic validation/policy/identity errors marked nonretryable; +- transient infrastructure/provider errors distinguishable; +- error cause layer preserved; +- an error code never reveals another tenant's resource existence. + +## 21. Pagination/streaming/backpressure + +Large observations/extractions/downloads use bounded pagination or streaming with declared maximum chunk/message sizes. The runtime can stop producers when resource budgets are hit. Client refusal to consume data does not create unbounded buffering. + +## 22. Concurrency + +- sessions/contexts are independently scoped; +- node/action validation occurs at execution time; +- secret handle use is atomic at the trusted broker; +- one protocol request cannot hold an unbounded global lock; +- mutable task transitions use explicit compare/version or equivalent serialization semantics; +- duplicated/concurrent state-changing requests obey idempotency/quarantine rules. + +## 23. Authentication vs authorization + +Protocol transport authentication proves the calling human/workload identity. Authorization additionally depends on tenant, session, purpose, capability, origin, action/risk, data scope, destination and approvals. “Authenticated” is never equivalent to “can browse/fill/export anything.” + +## 24. Adapter mappings + +### WebDriver BiDi + +Maps session/user-context/browsing-context capabilities into scoped OriginWeave identities. BiDi element/context identifiers remain adapter-local. + +### Chrome DevTools Protocol + +Maps selected versioned Network/DOMSnapshot/Accessibility/Tracing and other explicitly reviewed domains. `Runtime.evaluate` is not automatically mapped to standard `browser.act`. + +### WebMCP + +Maps site-provided tool descriptors and results into untrusted typed observations/tool proposals. Experimental upstream status is preserved; missing WebMCP falls through to other observation channels. + +### Model Context Protocol + +Exposes the bounded high-level OriginWeave operations to orchestrators. MCP server credentials do not expose raw Chromium, cookie or secret state. + +## 25. Public Rust API + +The Rust crates remain independently reusable. Wire DTOs must not force core crates to depend on HTTP/MCP/CDP. Translation layers convert between transport schemas and stable core value objects. + +## 26. Change control + +A change to identity scope, action semantics, error/retry behavior, idempotency, secret/sensitive disclosure, post-condition truth, protocol capability, evidence semantics or version compatibility requires TRD/traceability updates and normally a dedicated ADR when it changes a governing authority boundary. + +No external SDK can be declared stable until the wire schemas, compatibility policy and conformance tests are published on a protected release. diff --git a/docs/DATA_GOVERNANCE.md b/docs/DATA_GOVERNANCE.md new file mode 100644 index 000000000..00dea98ae --- /dev/null +++ b/docs/DATA_GOVERNANCE.md @@ -0,0 +1,334 @@ +# OriginWeave Data Governance and Privacy Boundary + +- **Document status:** Proposed authoritative product baseline +- **Product status:** Pre-alpha +- **Scope:** OriginWeave-owned runtime contracts plus explicit host/enterprise ownership boundaries +- **Related:** [`PRD.md`](PRD.md), [`TRD.md`](TRD.md), [`THREAT_MODEL.md`](THREAT_MODEL.md), [`OPERABILITY.md`](OPERABILITY.md), [`erd/README.md`](erd/README.md), [`traceability/README.md`](traceability/README.md) + +## 1. Purpose + +OriginWeave must support enterprise web tasks that genuinely require personal, confidential, credential, or customer data without solving privacy risk by blanket masking that makes the task impossible. The product therefore rejects both ambient raw-value propagation and indiscriminate masking. + +The governing rule is: + +> **Keep authoritative data usable by explicitly authorized business processes while replacing ambient propagation with purpose-bound, field-scoped, just-in-time disclosure and durable evidence that does not copy the protected value.** + +This document defines the product data-governance contract. It is not a legal opinion, certification, or claim that every planned enterprise control is already implemented. + +## 2. Status discipline + +Protected `main` is the implementation authority. + +- **Implemented:** protected-main code and tests provide the stated behavior. +- **Accepted architecture:** a governing ADR/architecture decision establishes the direction, but the complete runtime path may not yet exist. +- **In progress:** an active PR implements part of the contract; it is not shipped behavior. +- **Planned:** roadmap-aligned but not yet implemented. +- **Proposed:** requires additional reviewed design or implementation evidence. + +Current protected-main foundations include deterministic policy/evidence types, canonical origin authority, bounded resource/evidence contracts, and credential-free evidence principles. Purpose-bound sensitive-data policy and sensitive-access receipts are active development lines and must not be represented as protected-main completion until merged. + +## 3. Data classes + +OriginWeave uses explicit classifications rather than assuming every value has the same handling requirements. Product integrations should map local classifications into a versioned policy domain that can represent at least: + +- `public_data`; +- `internal_data`; +- `personal_data`; +- `sensitive_personal_data`; +- `credential_data`; +- `payment_data`; and +- customer-defined classes with an explicit policy version. + +A classification is policy input, not authorization. Classification changes invalidate previously derived disclosure authority when the new class is not covered by the original decision. + +## 4. Authority model + +Every sensitive-data transition is a distinct resource-access decision. Network location, repository membership, administrator role, possession of a model key, or ownership of a browser session never implies full disclosure. + +A disclosure decision must bind, where applicable: + +- tenant identity; +- human/workload/service/device identity; +- authenticated session identity; +- delegated task identity; +- exact field identifiers and record scope; +- business purpose; +- action kind; +- canonical destination origin or connector; +- data classification; +- model/provider/region/retention mode when AI is involved; +- requested retention/export behavior; +- approval or break-glass evidence; and +- policy/control version. + +Supported decision outcomes are conceptually: + +- `deny_access`; +- `opaque_handle_only`; +- `derived_value_only`; +- `partial_field_disclosure`; +- `full_field_disclosure`; +- `human_approval_required`; and +- `dual_control_required`. + +An approval-required result is a control state, not execution authority. The exact authority must be re-evaluated after approval and immediately before disclosure. + +## 5. Opaque handles and trusted broker boundary + +The planner/model receives an opaque handle by default, not the protected value. The trusted broker or trusted browser adapter resolves a handle only after rechecking the current authority. + +A future production `sensitive_value_handle` must be bound to at least: + +- one tenant; +- one task; +- one field set; +- one business purpose; +- one destination/audience; +- one data classification; +- an exclusive expiry; +- a bounded maximum use count; and +- a policy version or invalidation epoch. + +Atomic reservation/increment, trusted current time, revocation, concurrent/replay protection, value resolution, and compensation semantics are trusted-broker responsibilities. A pure policy predicate must never be documented as if it atomically consumes a handle. + +Handles must not be serialized into long-term model memory, URLs, screenshots, telemetry, crash dumps, clipboard history, public provenance, or browser-visible page content. + +## 6. Model disclosure + +Raw protected data may enter a model request only when deterministic or handle-based execution cannot satisfy the approved task and an explicit model-disclosure policy authorizes it. + +The decision must bind the exact fields, purpose, provider, model, region, retention/training mode, request lifetime, output schema, and approval class. Provider outage or policy mismatch fails closed; it must not silently fall back to a less trusted provider or region. + +Model credentials remain outside model-visible context. `NVIDIA_NIM_API_KEY` is a development/approved runtime credential only where an explicit model-backed path requires it and never becomes an application data-governance shortcut. + +Model output is untrusted data. It cannot create new disclosure authority, expand a field set, change a destination, or override deterministic browser/network policy. + +## 7. Browser and page disclosure + +A trusted browser fill may reveal a value to an approved page only after the runtime revalidates: + +- browser session and browsing context; +- current document epoch; +- canonical page origin; +- actionable node/field identity; +- delegated task and purpose; +- field classification; +- handle expiry/use state; +- current approval/policy version; and +- post-condition expectations. + +Protected values must not be exposed through hidden DOM, accessibility labels, page logs, screenshots, clipboard state, or unrelated form fields merely because the approved page can receive one value. + +A successful input command is not durable evidence that the intended business operation succeeded. The trusted adapter must observe the expected post-condition and record the action result separately from disclosure authority. + +## 8. Data stores and persistence ownership + +OriginWeave core currently does not claim a production application database. The conceptual ERD therefore distinguishes runtime/domain entities from persistence that is host-owned or planned. + +Where an embedding product persists sensitive information, recommended conceptual records include: + +- `sensitive_data_record`; +- `sensitive_field_definition`; +- `sensitive_data_request`; +- `sensitive_access_decision`; +- `sensitive_value_handle`; +- `sensitive_access_evidence`; +- `business_purpose_record`; +- `field_disclosure_policy`; +- `tenant_security_policy`; +- `model_disclosure_policy`; +- `provider_region_policy`; +- `encryption_key_reference`; +- `retention_policy_record`; +- `approval_evidence_record`; +- `break_glass_event`; +- `control_evidence_mapping`; +- `audit_sequence_record`; and +- `deletion_receipt_record`. + +Physical persistence requires a separate accepted ADR, tenant model, migrations, backup/restore, retention, encryption, authorization, audit, and rollback design. All owned database objects use descriptive two-or-more-word `snake_case` names. + +## 9. Encryption, tokenization, and derived values + +Protected values at rest require encryption appropriate to the deployment boundary. Product architecture should support versioned key references, rotation, revocation, customer-managed-key policy where required, and cryptographic-deletion evidence without putting key material into evidence records. + +Reversible tokenization, deterministic encryption, or format-preserving transforms are allowed only for an explicit interoperability or join requirement with documented residual risk. Hashing must not be described as anonymization where the original value space is enumerable or linkable. + +Derived values are independently classified. A summary, embedding, screenshot, token, model output, or provenance artifact is not automatically non-sensitive merely because it differs from the source value. + +## 10. Logging and observability + +Raw protected values are excluded by default from: + +- application logs; +- tracing/span attributes; +- metric labels; +- exception messages; +- GitHub issues and CI logs; +- crash/support bundles; +- analytics events; +- screenshots and clipboard history; +- model caches outside the approved disclosure contract; +- WARC/PROV exports unless a separate authorized evidence-retention policy explicitly allows protected content. + +Observability uses identifiers, classifications, policy versions, outcomes, counts, durations, and bounded reason codes instead of protected values. + +Credential-free evidence is not the same as public evidence. Tenant, actor, task, revision, provider, and destination metadata can remain confidential and must follow access and retention policy. + +## 11. Sensitive-access evidence + +A `sensitive_access_evidence` record must carry enough metadata to reconstruct the decision without copying the protected value. The evidence model should include, where applicable: + +- decision/request identifier; +- tenant, actor, workload, device, and task identifiers; +- field identifiers and classification; +- business purpose and canonical destination; +- decision outcome and policy/control versions; +- approval or break-glass reference; +- handle issuance/resolution/revocation metadata; +- model/provider/region/retention mode when applicable; +- encryption-key reference/rotation epoch without key material; +- decision, disclosure, completion, and retention-deadline times; and +- success/denial/partial/policy-change outcome. + +Tamper-evident sequencing is a planned enterprise evidence capability. A local immutable Rust value object is not by itself a durable append-only audit service. + +## 12. Retention, deletion, and legal hold + +Retention is attached to the artifact class, purpose, tenant policy, and legal/contractual requirement rather than a global timer. + +The lifecycle must distinguish: + +- task-local ephemeral material; +- operational records; +- authorized model artifacts; +- export artifacts; +- audit/control evidence; +- customer-configured retention; and +- legal hold. + +Deletion/revocation must propagate to caches, temporary files, search/vector derivatives, exports, model caches, and backup-expiry workflows as applicable. Deletion receipts retain identifiers and completion evidence but not the deleted value. + +Backup expiry and legal-hold behavior are deployment responsibilities and must not be invented by a core-library API. + +## 13. Data residency and provider policy + +Tenant policy may restrict storage, browser execution, model inference, support access, export, or evidence retention by region/provider. A destination or provider that violates the current region policy is denied rather than used as a fallback. + +Residency rules apply to derived artifacts too. Model responses, embeddings, screenshots, WARC bundles, diagnostics, and exported provenance cannot silently cross a region boundary simply because the original record remained local. + +## 14. Break-glass and support access + +Cross-tenant or privileged support access is disabled by default. A break-glass path must require: + +- explicit reason; +- appropriate approval or dual control; +- exact resource/purpose scope; +- short expiry; +- heightened monitoring; +- non-transferable identity; +- post-event review; and +- evidence that cannot be reused as a standing role grant. + +Break-glass does not bypass network/service identity, tenant isolation, retention, or evidence requirements. + +## 15. WARC, PROV, screenshots, and export + +OriginWeave's evidence-first product direction supports WARC-compatible source capture and PROV-compatible derivation export, but neither format creates a privacy exemption. + +A capture/export policy must classify and authorize: + +- raw HTTP bodies; +- headers/cookies/credentials; +- screenshots; +- DOM/semantic snapshots; +- extracted values; +- model inputs/outputs; +- action evidence; and +- derived provenance. + +Public/shareable evidence uses synthetic or approved public fixtures. Production protected content requires a separate purpose, audience, retention, encryption, and export authority. + +## 16. Tenant and service identity + +Every storage, queue, cache, object, search/vector, model, connector, export, support, and audit boundary must enforce tenant/resource identity in the embedding deployment. + +Service-to-service disclosure uses authenticated workload/service identity and explicit authorization. An authorized service must still be prevented from acting as a confused deputy for an unauthorized tenant, task, destination, or connector. + +OriginWeave does not treat a shared static credential as service identity. + +## 17. Accessibility and data minimization + +Accessibility cannot be implemented by leaking protected values into hidden DOM or accessible names. Authorized UI disclosure must preserve keyboard and assistive-technology use while limiting exposed fields to the current task step. + +UI surfaces should explain why access was granted, what category of data is in use, and when authority expires without exposing protected values in telemetry or unrelated status text. + +## 18. Compliance evidence boundary + +OriginWeave designs controls and evidence for CSAP/SOC 2 readiness but does not claim certification from code or documentation alone. + +A future `control_evidence_mapping` must distinguish: + +1. product capability; +2. configured control; +3. operating control; +4. collected evidence; +5. management assertion; and +6. independent certification/examination result. + +CSAP marks may be claimed only for the certified cloud service boundary. SOC 2 statements depend on the actual system description, included Trust Services Criteria, operating period, management assertion, and independent examination. + +## 19. Degraded behavior + +Data-governance failures are fail-closed for the affected disclosure: + +- unavailable policy -> no protected disclosure; +- unavailable broker -> no handle resolution; +- stale/expired handle -> no resolution; +- approval unavailable -> approval-required action remains blocked; +- provider/region mismatch -> no model fallback outside policy; +- audit/evidence failure where evidence is mandatory -> no high-risk completion claim; +- post-condition uncertainty -> action outcome is `unknown`/reconciliation-required rather than success. + +These failures block only the affected task/action. They do not justify weakening another tenant's policy or disabling unrelated deterministic browser functionality. + +## 20. Test and acceptance contract + +Release-relevant data-governance tests must include realistic flows, not only string redaction: + +- authorized shipping/form fill uses the required full value at the exact approved origin without exposing it to planner/model/log/evidence; +- wrong tenant/task/field/purpose/origin/classification fails closed; +- stale, expired, over-used, revoked, or replayed handle fails; +- concurrent handle use cannot cross audience or use-count authority; +- provider/model/region/retention policy changes invalidate an otherwise valid model disclosure; +- break-glass requires reason/approval/expiry and cannot create a durable role grant; +- log/trace/metric/crash/support/screenshot/clipboard/WARC/PROV scanners contain no unapproved protected bytes; +- key rotation/revocation and retention/deletion transitions have deterministic evidence; +- hostile Unicode and serialization ambiguity cannot broaden identifiers or policy authority; +- production functions/lines/regions/branches remain exactly 100% covered for OriginWeave-owned Rust behavior. + +Synthetic or explicitly approved fixtures are mandatory; production personal data is forbidden in repository tests. + +## 21. Standards and research traceability + +The governing references live in [`doctoring.md`](doctoring.md), the product-baseline addendum, feature-specific doctoring, and the ADR corpus. This document specifically relies on the product principles established by: + +- NIST SP 800-207 and SP 800-207A for explicit identity/resource policy rather than implicit network trust; +- NIST AI 600-1 for generative-AI risk-management inputs without replacing deterministic authorization; +- current KISA CSAP program requirements as a certification-readiness input, never a self-certification claim; and +- AICPA Trust Services Criteria as an assurance/control-evidence reference rather than a product feature checklist. + +Material legal or certification claims must be revalidated against the law, program criteria, contracts, deployment region, and operating procedures effective at the release date. + +## 22. Rollback and supersession + +This document may be superseded only through reviewed changes that preserve or explicitly migrate: + +- the no-ambient-disclosure principle; +- purpose/field/destination/classification binding; +- broker/opaque-handle separation; +- protected-value exclusion from generic telemetry/evidence; +- host-vs-core persistence ownership; and +- truthful certification/compliance claims. + +A rollback must not reintroduce blanket masking as the only privacy mechanism or ambient raw-value propagation as the convenience path. \ No newline at end of file diff --git a/docs/OPERABILITY.md b/docs/OPERABILITY.md new file mode 100644 index 000000000..8b8abe397 --- /dev/null +++ b/docs/OPERABILITY.md @@ -0,0 +1,376 @@ +# OriginWeave Operability Baseline + +- **Status:** Proposed authoritative operations baseline +- **Product status:** Pre-alpha; no production SLA is claimed +- **Architecture:** [`../ARCHITECTURE.md`](../ARCHITECTURE.md) +- **Threat model:** [`THREAT_MODEL.md`](THREAT_MODEL.md) +- **Release/rollback:** [`RELEASE_AND_ROLLBACK.md`](RELEASE_AND_ROLLBACK.md) + +## 1. Purpose + +OriginWeave is intended to run long-lived interactive and autonomous browser workloads under explicit security/resource authority. Operability therefore includes more than process uptime: operators must know whether the correct browser/task authority exists, whether a task can make safe progress, what external effect may already have happened, how evidence can be inspected, and how a release can be rolled back without silently weakening security. + +This document defines the target operational contract and marks pre-alpha gaps rather than inventing SLA commitments. + +## 2. Service modes + +Expected deployment modes are: + +- interactive OriginWeave Browser; +- headless OriginWeave Runtime; +- embedded module in another CWL product; +- future managed multi-tenant service. + +All modes share the Rust authority/evidence contracts. They may use different browser/process/persistence adapters but must not invent weaker semantics. + +## 3. Health model + +### Liveness + +Answers only whether the process/supervisor can make progress and respond to control operations. It does not claim browser readiness, model-provider readiness, destination reachability, or task success. + +### Readiness + +Requires the configured execution profile's mandatory local dependencies to be ready. For example, an interactive browser profile may require Chromium/process-control health while a model-backed autonomous task may additionally require the selected model route. + +A missing optional provider must not make deterministic non-model functions globally unready. + +### Task readiness + +Evaluated per task using exact policy, session/context, required adapter, secret/provider, resource, tenant and destination authority. One unavailable dependency blocks only tasks that need it. + +## 4. State model + +Operational task states should remain explicit: + +```text +created +authorized +active +observing +planning +awaiting_approval +acting +verifying +paused +recovering +completed +failed +cancelled +quarantined +``` + +`quarantined` is required when an external side effect may have occurred but current evidence cannot safely determine whether retry would duplicate or conflict with it. + +## 5. SLI catalogue + +Production profiles define exact computation and aggregation for each **SLI**. Candidate SLIs include: + +### Availability and task success + +- control-plane request availability; +- session creation success rate; +- delegated task completion rate; +- human-approved action success rate; +- recovery success after browser/adapter crash; +- provider-specific availability separated from product availability. + +### Latency + +- human input-to-render latency; +- task queue wait; +- observation generation latency; +- policy decision latency; +- connection/TLS/HTTP latency; +- model invocation latency; +- action-to-post-condition verification latency; +- end-to-end task latency by class. + +### Safety/correctness + +- unauthorized-action attempts blocked; +- stale-node action rejection; +- post-condition failure/uncertainty rate; +- destination/TLS/HTTP policy rejection classes; +- prompt-injection successful-action rate; +- provenance completeness; +- secret/PII leakage detections. + +### Resource + +- process/task/tab peak RSS; +- CPU worker saturation; +- GPU/VRAM pressure events; +- compositor/frame-health degradation; +- observation cache bytes; +- inference batch/offload/CPU-fallback rate. + +### Operations + +- restart/crash frequency; +- task cancellation completion time; +- checkpoint age; +- quarantine backlog; +- evidence/export failure rate; +- release/rollback success. + +## 6. SLO model + +OriginWeave does not publish numerical **SLO** values in pre-alpha documentation without benchmark/operational evidence. Release profiles must define: + +- which SLI is covered; +- target/threshold and measurement window; +- workload/hardware/browser/model assumptions; +- excluded planned maintenance; +- error budget policy; +- paging/ticket threshold; +- customer communication and remediation obligation where applicable. + +Security invariants such as cross-tenant disclosure or unauthorized high-risk action are not normalized into a permissive error budget; their acceptance threshold is zero for the tested supported conditions. + +## 7. Observability + +Target integration uses OpenTelemetry-compatible metrics, traces and structured events, but telemetry never becomes a raw-secret store. + +### Required correlation identifiers + +Where implemented and safe: + +```text +tenant_record_id +agent_session_id +browsing_context_id +action_intent_id +policy_decision_id +action_event_id +provenance_record_id +release_version +runtime_instance_id +``` + +Opaque identifiers are preferred. Do not put cookies, authorization headers, personal values or full unbounded page text into labels/attributes. + +### Event families + +- task/session lifecycle; +- browser/adapter lifecycle; +- policy/approval decision; +- network authority transition; +- action/post-condition transition; +- resource pressure and mitigation; +- model invocation metadata; +- persistence/evidence outcome; +- operator action and break-glass event; +- release/rollback event. + +## 8. Logging contract + +Logs are operational summaries, not primary evidence. Primary evidence uses typed credential-free records. + +Logs must: + +- use structured bounded fields; +- record causal identifiers and safe error classes; +- avoid raw protected values, headers, bodies and unrestricted URLs; +- distinguish expected policy denial from infrastructure failure; +- distinguish retryable transient error from deterministic failure; +- include exact software/build identity where useful. + +Operator tooling must support scanning logs/support bundles for synthetic protected test values. + +## 9. Alerting and triage + +### Page-level conditions + +Examples requiring immediate response in a production profile: + +- suspected cross-tenant access; +- secret/PII occurrence in disallowed telemetry/evidence; +- unexpected privileged action without matching policy/approval evidence; +- signing/provenance verification failure on deployed artifact; +- widespread crash loop or task corruption; +- evidence integrity/tamper failure. + +### Ticket-level conditions + +- rising provider/model timeout rate; +- repeated task quarantine; +- persistent resource saturation; +- extension compatibility regression; +- increased stale-node/post-condition failures; +- repeated destination/TLS/HTTP rejects indicating upstream drift. + +## 10. Incident response flow + +```text +detect +-> identify exact tenant/session/release/authority boundary +-> stop unsafe new admission +-> preserve credential-free evidence +-> quarantine ambiguous tasks/artifacts +-> assess external side effects +-> contain/revoke credentials or routes as needed +-> reproduce at smallest safe boundary +-> remediate and verify +-> rollback/release fixed artifact +-> post-incident control update +``` + +Do not retry an ambiguous externally mutating action merely to learn whether the first attempt succeeded. + +## 11. Break-glass operations + +A **break-glass** path is Planned for enterprise operation and must never be implemented as a reusable administrator bypass. + +Required contract: + +- explicit incident/support reason; +- authenticated eligible operator; +- separate approval/dual control for high-risk data access; +- narrow tenant/task/data scope; +- short expiry; +- no implicit extension to future tasks; +- elevated logging/evidence; +- post-event review; +- immediate revocation path. + +Break-glass does not disable origin/destination/TLS/evidence or release integrity controls. + +## 12. Quarantine and recovery + +Use **quarantine** when state cannot be safely retried or discarded automatically. Examples: + +- action request was transmitted but post-condition was not observable; +- browser crashed during externally visible mutation; +- evidence integrity mismatch; +- persistence state disagrees with external service; +- tenant/policy changed during operation and side effects are ambiguous. + +A quarantined task may be: + +- inspected read-only; +- reconciled against external authoritative state; +- completed manually; +- compensated through a separately authorized action; +- cancelled with evidence; +- resumed only after exact current authority is re-established. + +## 13. Cancellation + +Cancellation is cooperative but must have a bounded hard-stop escalation for local components. The task record distinguishes: + +- cancel requested; +- model/network/browser operation interrupted before external effect; +- external effect may have committed; +- browser context closed; +- resources reclaimed; +- evidence finalized. + +A cancelled task cannot silently reuse secret handles or approvals on later restart. + +## 14. Retry and backoff + +Retry policy is allow-listed by causal error class. + +- deterministic validation/permission/origin/identity/malformed-input errors: do not retry; +- selected transient network/provider states: bounded retry under one end-to-end deadline; +- ambiguous external mutation: quarantine/reconcile instead of automatic retry; +- broker/resource unavailability: defer task or fail closed according to task deadline, never substitute weaker authority. + +Backoff/circuit breaker belongs to the orchestration/adapter layer and cannot change lower-level security decisions. + +## 15. Capacity management + +Capacity profiles include: + +- max simultaneous browser sessions/contexts; +- CPU worker pool capacity; +- RAM and observation-cache budgets; +- GPU/VRAM reserved interactive capacity; +- model residency/batch limits; +- network/download limits; +- object/evidence storage rates; +- queue depth and maximum task age. + +Admission control uses current resource evidence and reviewed budgets. A declared capacity number without a load test is not a supported capacity claim. + +## 16. Browser and model upgrade operations + +### Chromium + +A supported update requires: + +- security/update rationale; +- API/protocol diff assessment; +- OriginWeave adapter build/test; +- MV3 compatibility suite; +- real task/observation/action regression; +- sandbox/Site Isolation preservation; +- canary and rollback artifact. + +### Model/provider + +Model updates are separately versioned from deterministic browser authority. Evaluate routing/tool use/schema compliance, prompt-injection robustness, task success, unsupported actions/claims, cost/latency and provider policy. Provider changes cannot silently expand protected-data eligibility. + +## 17. Persistence backup and recovery + +Planned durable adapters must define per data class: + +- authoritative vs reconstructible data; +- backup frequency and retention; +- encryption/key recovery; +- recovery point objective and recovery time objective when production SLOs exist; +- tenant deletion/legal hold behavior; +- artifact/digest verification after restore; +- evidence continuity and replay. + +Raw secrets use a dedicated trusted secret system and are not restored from general audit/evidence backups. + +## 18. Data retention and deletion + +Retention is purpose/data-class/tenant aware. Operators must be able to identify all declared durable copies of: + +- authoritative sensitive values; +- task/session metadata; +- screenshots/downloads; +- WARC source artifacts; +- model request/output artifacts; +- provenance/audit evidence; +- backups. + +Deletion/expiry produces metadata receipts where appropriate without retaining the deleted protected value. + +## 19. Security operations + +- dependency/SAST/security findings are triaged against exact release code; +- vulnerabilities use private coordinated disclosure; +- credentials/keys have rotation/revocation playbooks; +- egress and service identities are monitored against declared configuration; +- privileged operator access is reviewable; +- supply-chain provenance is verified before deployment. + +## 20. Deployment/configuration safety + +Configuration is versioned, validated and fail closed. Invalid limits, origins, routes, trust roots, model/provider policy, retention, tenant identity or required credentials prevent the affected feature/task from starting. Startup does not silently apply permissive defaults to recover from malformed security configuration. + +## 21. Operational acceptance for scheduler/automation fixes + +A CI-green workflow change is not operational proof. After protected merge, perform a real scheduled/manual run demonstrating the intended path on the protected exact head. Evidence includes trigger, head SHA, gating reason, credential boundary, action taken/not taken and resulting authoritative repository state. + +## 22. Runbook ownership + +As product surfaces become concrete, maintain focused runbooks for at least: + +- browser/session crash loop; +- task quarantine/reconciliation; +- secret/PII leakage response; +- TLS/destination policy outage; +- model/provider outage; +- extension/Chromium compatibility regression; +- resource saturation; +- persistence/evidence integrity incident; +- release rollback; +- tenant deletion/export; +- break-glass access. + +This baseline defines the common rules; surface-specific operational commands must live next to the actual implementation and be tested where automation is safe. diff --git a/docs/PRD.md b/docs/PRD.md new file mode 100644 index 000000000..12e5b7f0b --- /dev/null +++ b/docs/PRD.md @@ -0,0 +1,404 @@ +# OriginWeave Product Requirements Document + +- **Document status:** Proposed authoritative product baseline +- **Product status:** Pre-alpha +- **Product:** OriginWeave +- **Tagline:** **Browse. Act. Prove.** +- **Canonical architecture:** [`../ARCHITECTURE.md`](../ARCHITECTURE.md) +- **Technical requirements:** [`TRD.md`](TRD.md) +- **Data governance:** [`DATA_GOVERNANCE.md`](DATA_GOVERNANCE.md) +- **Roadmap:** [`product-roadmap.md`](product-roadmap.md) +- **Research and standards:** [`doctoring.md`](doctoring.md) + +## 1. Purpose + +This PRD defines the product boundary that previously existed across architecture, ADRs, implementation plans, roadmap entries, pull-request descriptions, and product-design conversations. It does not convert planned work into shipped functionality. Shipped implementation truth is determined from the consistent set of protected `main` source, executable tests, produced build/release artifacts, applicable migrations and configuration, and integrated operational evidence. If those authorities disagree, the discrepancy is a release/operability defect that must be resolved before the affected behavior is described as shipped; an Accepted ADR provides design authority but never overrides contrary executable or released evidence. + +OriginWeave is an enterprise agentic web runtime and provenance-native browser platform. Chromium remains the compatibility kernel; Rust owns the governance, authority, resource, evidence, and agent-facing control plane. + +## 2. Product vision + +A person or enterprise can delegate a bounded web task and receive the requested outcome together with evidence sufficient to understand what was observed, authorized, attempted, and verified. + +OriginWeave must provide: + +1. explicit task and execution-mode authority; +2. explicit browser/session/context/document identity; +3. typed actions instead of ambient arbitrary-script authority; +4. deterministic origin, destination, route, TCP, TLS and HTTP authority; +5. purpose-bound sensitive-data disclosure without model-visible raw secrets; +6. post-condition verification for state-changing work; +7. bounded resource governance that protects interactive browser correctness; +8. provenance that distinguishes source evidence, policy, model judgement, action and outcome; and +9. stable external adapters without making experimental browser protocols the product authority. + +## 3. Requirement status vocabulary + +Every requirement uses **exactly one** status from this table. Implementation evidence, active-PR detail, non-goal classification and dependency notes belong in separate columns or prose and never create composite status labels. + +| Status | Meaning | +|---|---| +| **Implemented** | Present on protected `main` with repository tests and documented authority boundaries. | +| **Accepted architecture** | A reviewed governing design direction; this status does not itself prove the complete runtime path is implemented. | +| **Planned** | In the product roadmap or accepted target architecture, but not a shipped capability. | +| **Proposed** | Product direction still requiring a dedicated reviewed decision or sufficient implementation evidence. | +| **Open** | A decision or acceptance criterion is intentionally unresolved. | + +Only `Implemented` may describe shipped behavior. An Accepted ADR is design authority, not implementation proof. + +## 4. Problem statement + +General browser automation often collapses distinct authorities: URL into network permission, DNS into safe destination, socket into authenticated service, selector into durable node identity, model output into executable code, credential possession into disclosure authority, command return into success, and browser logs into provenance. These shortcuts are unacceptable for a governed enterprise runtime because they make failure, security review and acquisition diligence ambiguous. + +## 5. Primary users and stakeholders + +### 5.1 Enterprise automation owner + +Needs delegated web work under explicit tenant, purpose, origin, risk, sensitive-data and resource policies. + +### 5.2 Security and governance administrator + +Needs least privilege, deterministic network authority, approval evidence, purpose-bound data handling, tenant separation, supply-chain evidence and incident reconstruction. + +### 5.3 Agent platform engineer + +Needs a stable typed protocol that does not couple the orchestrator to Chromium-local identifiers, raw secrets or one experimental automation surface. + +### 5.4 Data and research engineer + +Needs structured extraction with exact source locators, hashes, capture time, derivation and model provenance. + +### 5.5 Human browser user + +Needs Chromium-compatible browsing to remain responsive and understandable while assistance or delegated tasks operate under separate authority. + +### 5.6 Operator and procurement reviewer + +Needs observable failure modes, operability, rollback, SBOM/provenance, compatibility, accessibility and supportable deployment boundaries. + +## 6. Product family + +The status applies to the **whole named product surface**, not to every implemented foundation underneath it. Partial protected-main foundations are called out explicitly so a product-family row never promotes an unfinished surface to shipped functionality. + +| Surface | Product responsibility | Status | Implementation evidence / note | +|---|---|---|---| +| **OriginWeave Browser** | Chromium-compatible interactive distribution with governed agent entry points | Planned | No protected-main branded browser distribution yet | +| **OriginWeave Runtime** | Headless/embedded governed web-task runtime | Planned | Rust authority kernels exist; browser integration remains incomplete | +| **OriginWeave Observe** | Structured observation from tools, structured data, network, accessibility, DOM/layout and visual fallback | Planned | Session/context/node-authority foundations are on protected main; semantic browser observation adapter is incomplete | +| **OriginWeave Capture** | Schema-bound extraction, crawler controls, downloads and WARC/PROV-oriented capture | Planned | Evidence foundations exist; complete capture runtime not shipped | +| **OriginWeave Governor** | CPU, RAM, GPU, VRAM, admission and model/browser priority governance | Accepted architecture | Deterministic resource-budget and CPU-worker admission foundations are implemented; platform telemetry/scheduling adapters remain incomplete | +| **OriginWeave Policy** | Capability, origin, purpose, risk, crawler, approval and sensitive-data authority | Accepted architecture | Capability/origin/purpose/risk/crawler/approval foundations are implemented; purpose-bound sensitive-data policy is active work in PR #33 and the trusted broker remains planned | +| **OriginWeave Evidence** | Credential-free evidence, provenance and task-trail contracts | Accepted architecture | Credential-free network evidence and purpose-bound sensitive-access receipts are implemented; complete Evidence Trail, WARC/PROV adapters and durable enterprise storage remain planned | +| **OriginWeave Protocol** | Stable browser-agent protocol independent of one upstream automation standard | Planned | Contract documented; implementation pending | +| **OriginWeave SDK** | Typed client libraries and adapters | Planned | Not a shipped product surface | +| **OriginWeave Enterprise** | Managed policy, tenancy, SSO/SCIM, residency, audit, deployment and support | Planned | Enterprise persistence/control plane not shipped | + +## 7. Execution modes + +### 7.1 Human Mode + +**Status:** Accepted architecture. + +Person-controlled browsing. Autonomous control is denied unless separately activated; ordinary installed extensions remain governed by Chromium and enterprise policy. Human input/rendering has priority over optional agent/model work. + +### 7.2 Assist Mode + +**Status:** Accepted architecture. + +The system can read, summarize and prepare reversible work, but state-changing behavior follows the same typed action, policy and approval path as delegated automation. Runtime integration is tracked as implementation work, not as part of the status label. + +### 7.3 Agent Task Mode + +**Status:** Accepted architecture. + +A delegated task uses a task-scoped isolated browser context/profile policy, explicit capabilities, origins, purposes, sensitive-data authority and resource budget. It must not inherit unrestricted Human Mode authority by convenience. + +### 7.4 Crawler Mode + +**Status:** Accepted architecture. + +Governed public collection is read-only, robots/rate/resource/purpose/retention aware, and does not include CAPTCHA solving, fingerprint evasion or deliberate access-control circumvention. + +## 8. Core user journeys + +### 8.1 Delegated web task + +```text +user goal +-> create isolated session +-> establish task authority +-> navigate through governed network/service boundaries +-> observe structured page state +-> propose typed action +-> evaluate deterministic policy and approval +-> execute through trusted adapter +-> verify expected post-condition +-> record credential-free evidence +-> return result + evidence trail +``` + +### 8.2 Evidence-first extraction + +```text +requested schema +-> typed/site-provided data when available +-> structured metadata +-> bounded network data +-> accessibility + DOM + layout +-> bounded visual fallback +-> schema/value validation +-> source/provenance binding +-> export value + evidence +``` + +### 8.3 Sensitive form completion + +```text +planner identifies field + purpose + destination +-> policy evaluates exact scope +-> planner receives opaque handle only +-> trusted broker revalidates current authority +-> trusted browser path receives minimum required value +-> post-condition is verified +-> disclosure receipt records metadata without protected value +``` + +The full journey is target architecture until the sensitive policy, trusted broker, browser-fill path, and post-condition/evidence path are all protected-main integrated. Implemented subcomponents do not make this whole sequence shipped. + +### 8.4 Enterprise crawler + +```text +public-crawl purpose +-> origin scope +-> robots/rate/retention policy +-> bounded read-only navigation +-> structured extraction +-> evidence/provenance export +``` + +## 9. Functional requirements + +### 9.1 Compatibility + +| ID | Requirement | Status | Implementation evidence / note | +|---|---|---|---| +| PRD-COMP-001 | Chromium is the compatibility kernel; OriginWeave does not reimplement Blink or V8 | Accepted architecture | ADR 0001 | +| PRD-COMP-002 | Maintain a Manifest V3 compatibility matrix and representative extension test farm | Planned | Issue #27 / release-specific evidence required | +| PRD-COMP-003 | Chromium-specific integrations remain behind versioned adapters | Planned | Adapter strategy ADR 0107 | +| PRD-COMP-004 | Headless runtime remains independently usable without the interactive browser UI | Planned | Modular architecture target | + +### 9.2 Session and observation authority + +| ID | Requirement | Status | Implementation evidence / note | +|---|---|---|---| +| PRD-OBS-001 | Autonomous observations can carry explicit browser-session, browsing-context, canonical-origin and document-epoch authority | Implemented | `ObservedNodeHandle`, `BrowserSessionId`, `BrowsingContextId` and `DocumentEpoch` on protected main via #17; real browser adapter remains planned | +| PRD-OBS-002 | Actionable semantic-node handles are invalidated by relevant document-epoch changes at the action linearization boundary | Accepted architecture | Core exact-authority validation exists; adapter lifecycle/mutation invalidation and atomic dispatch evidence remain planned | +| PRD-OBS-003 | Observation prefers typed/structured evidence before accessibility/DOM/layout and bounded visual fallback | Accepted architecture | ADR 0103 | +| PRD-OBS-004 | Observation can use bounded incremental updates rather than full repeated snapshots | Planned | Adapter-specific design needed | +| PRD-OBS-005 | Source channel and trust/provenance remain explicit | Accepted architecture | Evidence model foundations exist | + +### 9.3 Typed action execution + +| ID | Requirement | Status | Implementation evidence / note | +|---|---|---|---| +| PRD-ACT-001 | Actions carry typed kinds, risk classes, canonical targets and immutable intent digests | Implemented | `originweave-core` / policy foundations | +| PRD-ACT-002 | Arbitrary JavaScript is not an ordinary autonomous production tool | Accepted architecture | ADR 0102 | +| PRD-ACT-003 | Standard browser actions are exposed through versioned typed contracts | Planned | Browser adapter not complete | +| PRD-ACT-004 | Command completion alone is not success; expected post-condition must be observed | Accepted architecture | Evidence/action design | +| PRD-ACT-005 | High-risk approval is bound to exact intent and target | Implemented | Protected-main safety kernel | + +### 9.4 Network and service authority + +| ID | Requirement | Status | Implementation evidence / note | +|---|---|---|---| +| PRD-NET-001 | Logical origin is distinct from resolved destination authority | Implemented | `originweave-core` + destination policy | +| PRD-NET-002 | Resolution snapshots are bounded, origin-bound and fail closed on unapproved expansion | Implemented | `originweave-destination` | +| PRD-NET-003 | Direct transport connects only to approved canonical sockets and verifies `peer_addr` | Implemented | `originweave-network` | +| PRD-NET-004 | TLS authenticates service identity over the exact governed transport with explicit roots/time | Implemented | `originweave-tls` | +| PRD-NET-005 | Proxy/PAC route authority is explicit and never ambient | Implemented | Protected-main route-authority foundation from #20; PAC evaluation, proxy transport and CONNECT remain planned | +| PRD-NET-006 | Bounded HTTP semantics operate over authenticated governed transport | Planned | Active PR #11 is not shipped evidence | +| PRD-NET-007 | Real Chromium navigation proves end-to-end consumption of every shipped authority layer | Planned | Issue #28 / release acceptance requirement | + +### 9.5 Secret and sensitive-data authority + +| ID | Requirement | Status | Implementation evidence / note | +|---|---|---|---| +| PRD-DATA-001 | Raw secret values never enter model-visible context | Accepted architecture | ADR 0104; trusted browser/broker runtime path not fully shipped | +| PRD-DATA-002 | Sensitive disclosure binds tenant/task/field/purpose/destination/classification | Planned | Active replacement PR #33; no active-PR evidence counts as protected-main implementation | +| PRD-DATA-003 | Trusted broker owns expiry, revocation, atomic use reservation and resolution | Planned | Broker implementation pending under issue #10 | +| PRD-DATA-004 | Privacy controls use purpose-bound authorization, encryption, retention and audit rather than blanket masking | Accepted architecture | `DATA_GOVERNANCE.md` | +| PRD-DATA-005 | Model disclosure additionally binds provider/model/region/retention policy | Planned | Requires orchestrator/provider integration | + +### 9.6 Evidence and provenance + +| ID | Requirement | Status | Implementation evidence / note | +|---|---|---|---| +| PRD-EVD-001 | Generic network evidence is credential-free and value-redacted | Implemented | Protected-main evidence kernel | +| PRD-EVD-002 | Evidence binds validated source identity and digests | Implemented | Protected-main evidence foundations | +| PRD-EVD-003 | Evidence Trail links source, model judgement, policy, approval, action and verified outcome as distinct authorities | Planned | Conceptual ERD/provenance ADR; complete trail is not shipped | +| PRD-EVD-004 | **Origin Map** provides buyer-visible provenance exploration | Proposed | UX/product-design work still required | +| PRD-EVD-005 | WARC and PROV are separate interoperability/export adapters | Accepted architecture | ADR 0106 | +| PRD-EVD-006 | Sensitive-access evidence records authority without protected value | Implemented | Protected-main purpose-bound sensitive-access receipts via #31 | + +### 9.7 Resource governance + +| ID | Requirement | Status | Implementation evidence / note | +|---|---|---|---| +| PRD-RES-001 | Deterministic resource budgets produce cumulative mitigations | Implemented | `originweave-resource` foundations | +| PRD-RES-002 | Browser/human correctness outranks optional model throughput | Accepted architecture | ADR 0105 | +| PRD-RES-003 | CPU worker saturation participates in deterministic new-work admission | Implemented | Protected-main `ResourceSnapshot`/`ResourceGovernor` CPU-worker admission via #30; platform worker telemetry/actuation remains adapter work | +| PRD-RES-004 | Platform adapters report bounded CPU/RAM/GPU/VRAM/network/storage telemetry | Planned | Platform integration required | +| PRD-RES-005 | Constrained GPU systems shrink/offload/pause model work before sacrificing governed browser correctness | Accepted architecture | ADR 0105 | + +### 9.8 External agent interoperability + +| ID | Requirement | Status | Implementation evidence / note | +|---|---|---|---| +| PRD-INT-001 | WebDriver BiDi is a versioned adapter, not core authority | Planned | W3C draft tracked | +| PRD-INT-002 | CDP capabilities are pinned/version-gated | Planned | Chromium-specific adapter | +| PRD-INT-003 | WebMCP is optional, experimental and untrusted-content aware | Planned | Adapter required | +| PRD-INT-004 | MCP integrates through the Rust control plane rather than directly owning Chromium | Planned | MCP adapter required | +| PRD-INT-005 | OriginWeave Protocol is the stable internal/external semantic boundary | Planned | API contract defined | + +### 9.9 Extensions + +| ID | Requirement | Status | Implementation evidence / note | +|---|---|---|---| +| PRD-EXT-001 | Manifest V3 remains the extension compatibility baseline | Accepted architecture | Official Chrome platform baseline | +| PRD-EXT-002 | Upstream extension APIs are preserved where possible | Accepted architecture | Chromium-kernel strategy | +| PRD-EXT-003 | Extension access to agent authority requires separate signed policy grant | Planned | Issue #27 / enterprise-runtime integration | +| PRD-EXT-004 | Compatibility tests cover install/update, worker lifecycle, scripts, storage, DNR, messaging, download, side panel and isolation | Planned | Issue #27 / release-specific suite | + +### 9.10 Crawler and capture policy + +| ID | Requirement | Status | Implementation evidence / note | +|---|---|---|---| +| PRD-CRAWL-001 | Crawler mutation is denied and robots policy is explicit | Implemented | Safety-kernel policy foundation | +| PRD-CRAWL-002 | Rate, depth, count, concurrency, retention, purpose and export controls are explicit | Planned | Crawler runtime work required | +| PRD-CRAWL-003 | CAPTCHA bypass, fingerprint evasion and deliberate access-control circumvention are excluded | Accepted architecture | ADR 0108; capability remains prohibited | + +### 9.11 Enterprise operation + +| ID | Requirement | Status | Implementation evidence / note | +|---|---|---|---| +| PRD-ENT-001 | SSO/SCIM, tenant isolation, managed policy, regional residency, encrypted profiles and break-glass controls | Planned | Enterprise control plane not shipped | +| PRD-ENT-002 | OpenTelemetry-compatible observability reports task, stale-action, policy, resource and recovery evidence without protected values | Planned | Operability contract | +| PRD-ENT-003 | Operator workflows support cancellation, quarantine, replay, crash recovery, rollback and controlled upgrade | Planned | Operability contract | +| PRD-ENT-004 | Procurement evidence includes SBOM, provenance, reproducibility and compatibility matrices | Planned | Release contract | + +## 10. Non-functional requirements + +### 10.1 Correctness and fail-closed semantics + +- Rust-owned production behavior uses exact coverage and meaningful contract/property/integration tests. +- Network, browser, secret and evidence authority fail closed on ambiguity. +- State-changing success requires post-condition evidence. +- Old-head, synthetic, status-only or model-only evidence never upgrades the current source state. + +### 10.2 Security and privacy + +- Renderer compromise is in scope. +- Page/tool/download/model data is untrusted observation. +- Deterministic policy cannot be weakened by model output. +- Generic evidence/logging excludes raw credentials and protected values. +- Sensitive disclosure follows [`DATA_GOVERNANCE.md`](DATA_GOVERNANCE.md). +- Cross-tenant and confused-deputy tests are required before corresponding enterprise claims. + +### 10.3 Resource reliability + +- All potentially attacker-controlled byte/count/depth/time/concurrency dimensions are bounded at their trust boundary. +- Model work must not make state-changing browser work unverifiable. +- Admission failure is explicit rather than silent overcommit. + +### 10.4 Performance + +Performance goals are profile- and hardware-specific. Product releases must publish measured baselines rather than invented universal latency targets. Required dimensions include foreground input/frame behavior, task throughput, observation size/compression, peak RAM/VRAM, model fallback cost, extraction accuracy and task success stability. + +### 10.5 Accessibility + +- Product UI targets WCAG 2.2 AA where applicable. +- Keyboard operation, focus visibility, accessible names/states, non-color-only signals and exact-value/evidence alternatives are release requirements for shipped UI. +- Accessibility must not leak protected values into hidden DOM or accessible labels. + +### 10.6 Operability + +- Every production failure has a typed or bounded classification and recovery/rollback path. +- Operator evidence excludes raw secrets and uncontrolled page content. +- SLI/SLO/RPO/RTO values are measured deployment-profile evidence, not architecture prose. + +### 10.7 Packaging and supply chain + +- External actions/dependencies are pinned according to repository policy. +- Release evidence includes dependency/security scanning, SBOM/provenance and artifact identity. +- Reproducibility claims apply only when exact artifact comparison proves them. + +## 11. Buyer-visible acceptance + +A commercial release is accepted only when the integrated exact protected source head and produced release evidence prove the claims actually included in that release. + +Minimum acceptance families: + +1. exact CI/security/SAST/coverage/rustdoc evidence; +2. qualifying independent non-author review when current GitHub or explicit operational governance requires it; +3. protected branch/ruleset acceptance with zero valid unresolved findings; +4. browser/version/extension compatibility evidence for claimed surfaces; +5. realistic DNS/route/TCP/TLS/HTTP/navigation security tests for claimed network paths; +6. hostile prompt/node/secret/tenant/resource tests for claimed agent paths; +7. accessibility evidence for shipped UI; +8. package/SBOM/provenance/reproducibility evidence; +9. migration/configuration/rollback/recovery evidence for changed durable/runtime contracts; and +10. post-publication artifact verification against the intended source/release identity. + +No emergency or executive path may convert missing required evidence into a successful release. + +## 12. Degraded behavior + +Failures are scoped to the affected capability: + +- unsupported browser adapter -> disable governed capability, never raw-script fallback; +- stale node -> reject and re-observe; +- unavailable broker/policy -> no protected disclosure; +- model/provider failure -> deterministic path continues where independent; model-required task fails or uses only policy-approved fallback; +- resource pressure -> bound/reduce/pause optional work before compromising browser correctness; +- evidence failure for governed state-changing action -> no proved-success claim; +- crawler challenge/rate/robots block -> stop/degrade affected origin without evasion. + +## 13. Non-goals + +The following are not product capabilities unless a future reviewed product decision explicitly changes the boundary: + +- Blink/V8/browser-engine rewrite; +- arbitrary JavaScript as the ordinary autonomous action interface; +- model-visible raw-secret delivery; +- implicit trust from network location, browser profile, extension install or credential possession; +- CAPTCHA solving, fingerprint spoofing, residential-proxy rotation or access-control circumvention; +- blanket PII masking as the only privacy control; +- unbounded raw HTML/screenshot/network retention; +- universal legal/copyright authorization inferred from `robots.txt`; +- self-declared CSAP/SOC 2/ISO certification; +- merging or releasing by bypassing required checks, currently applicable review governance, branch protection, or reproducibility/provenance evidence. + +## 14. Product metrics + +Release and product evaluation should include: + +- repeated task success and variance; +- unauthorized-action rate; +- stale-node action rejection rate; +- injection-induced authority-escalation rate; +- extraction precision/recall and provenance completeness; +- peak RAM/VRAM and browser frame/input degradation; +- recovery success after browser/model/network failure; +- secret/protected-value leakage rate in model/log/evidence corpus; +- browser/extension compatibility pass rate; +- release provenance completeness. + +## 15. Ownership and integration + +OriginWeave remains independently usable. CWL integrations use explicit versioned APIs/events/artifacts; no sibling service receives direct OriginWeave application-database authority by default. Central `.github`, contextual-orchestrator, EgressWeave, naruon and other products retain their own writer/authority boundaries. + +## 16. Change control + +A material change to product identity, execution modes, action authority, browser/node lifetime, network authority, secrets/data governance, resource priority, evidence/provenance, crawler behavior, enterprise tenancy, protocol adapters or release acceptance requires the affected PRD/TRD/Architecture/ADR/UML/ERD/threat/test/operability/traceability views to be updated or explicitly proven unaffected. + +Status changes occur only from fresh evidence. `Accepted architecture` never automatically becomes `Implemented`; active PR work stays non-shipped until protected integration and exact acceptance evidence exist. diff --git a/docs/README.md b/docs/README.md index 85ee08125..fa62037e5 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,12 +1,38 @@ # Documentation Index +## Authoritative product documentation + +- [Product Requirements Document (PRD)](PRD.md) +- [Technical Requirements Document (TRD)](TRD.md) - [Architecture](../ARCHITECTURE.md) +- [Architecture Decision Record index](adr/README.md) +- [UML and control-flow diagrams](uml/README.md) +- [Conceptual ERD and durable domain model](erd/README.md) +- [Data governance and privacy boundary](DATA_GOVERNANCE.md) +- [Product and decision traceability](traceability/README.md) +- [Threat model](THREAT_MODEL.md) +- [Product-wide test strategy](TEST_STRATEGY.md) +- [Operability and incident-response baseline](OPERABILITY.md) +- [OriginWeave API and protocol contract](API_CONTRACT.md) +- [Release and rollback contract](RELEASE_AND_ROLLBACK.md) - [Product roadmap](product-roadmap.md) +- [Research and standards](doctoring.md) +- [Current product-baseline standards addendum](doctoring/product-documentation-baseline.md) - [Quality gates](quality-gates.md) +- [Security policy](../SECURITY.md) + +The PRD/TRD/Architecture/ADR/UML/ERD/data-governance/traceability/security/operations/API/release set is the product-wide documentation graph. Feature-specific design specifications and plans below provide detailed implementation history but do not substitute for the product-wide baseline. Planned or conversation-derived capabilities must remain labelled Planned, Proposed, or Open until reviewed implementation evidence reaches protected `main`. + +## Governance and maintenance + - [Destination registry maintenance](registry-maintenance.md) - [Database naming](database-naming.md) -- [Research and standards](doctoring.md) -- [Architecture decisions](adr/) +- [Agent/contributor rules](../AGENTS.md) +- [Contributing](../CONTRIBUTING.md) +- [Changelog](../CHANGELOG.md) + +## Approved and historical design specifications + - [Approved safety-kernel design](superpowers/specs/2026-08-05-agent-safety-kernel-design.md) - [Safety-kernel implementation plan](superpowers/plans/2026-08-05-agent-safety-kernel.md) - [Resolved-destination policy design](superpowers/specs/2026-08-06-resolved-destination-policy-design.md) @@ -15,6 +41,14 @@ - [Direct socket binding implementation plan](superpowers/plans/2026-08-06-direct-socket-binding.md) - [TLS service-identity design](superpowers/specs/2026-08-06-tls-server-identity-design.md) - [TLS service-identity implementation plan](superpowers/plans/2026-08-06-tls-server-identity.md) + +## Protected-main architecture decisions + +- [ADR 0001: Chromium compatibility kernel](adr/0001-chromium-compatibility-kernel.md) +- [ADR 0002: Agent safety kernel](adr/0002-agent-safety-kernel.md) +- [ADR 0003: Provenance-native observation](adr/0003-provenance-native-observation.md) - [ADR 0004: Logical origin and resolved destination safety](adr/0004-resolved-destination-policy.md) - [ADR 0005: Exact direct TCP peer binding](adr/0005-direct-socket-binding.md) - [ADR 0006: TLS service identity over the verified peer](adr/0006-tls-server-identity.md) + +See the [ADR index](adr/README.md) for status rules, required decision structure, and the rule that active-PR ADRs do not become Accepted merely because they exist on an unmerged branch. diff --git a/docs/RELEASE_AND_ROLLBACK.md b/docs/RELEASE_AND_ROLLBACK.md new file mode 100644 index 000000000..9063b6880 --- /dev/null +++ b/docs/RELEASE_AND_ROLLBACK.md @@ -0,0 +1,314 @@ +# OriginWeave Release and Rollback Contract + +- **Status:** Proposed authoritative release baseline +- **Product status:** Pre-alpha; there is no supported production release yet +- **Quality strategy:** [`TEST_STRATEGY.md`](TEST_STRATEGY.md) +- **Operability:** [`OPERABILITY.md`](OPERABILITY.md) +- **Changelog:** [`../CHANGELOG.md`](../CHANGELOG.md) + +## 1. Purpose + +A release is a verified immutable product artifact, not a branch, pull request, green model verdict or version string. OriginWeave may publish a supported version only when the exact integrated protected head and the artifacts derived from it satisfy the security, compatibility, quality, provenance, operability and rollback contract defined here. + +## 2. Release sources + +A production release is cut only from the exact current **protected main** tip or an immutable release commit derived by the repository's documented protected process. Required evidence cannot come solely from: + +- a feature branch; +- a predecessor head; +- a synthetic merge commit not used for the artifact; +- a cancelled/skipped/queued/pending/neutral/missing required check; +- an author/self review; +- an automated comment/status presented as independent formal approval. + +## 3. Version decision + +Use semantic versioning according to the supported public compatibility surface. + +Before `1.0.0`, the version still communicates artifact identity and change history but does not imply a frozen public API. Breaking pre-1.0 changes must still be documented clearly. + +A version bump requires: + +- explicit release scope; +- updated `CHANGELOG.md` moving validated entries from `Unreleased` into the release section; +- exact release commit/artifact identity; +- published supported-browser/protocol/deployment profile; +- migration and **rollback** decision. + +## 4. Release gate inventory + +The exact artifact source must satisfy all repository-required gates plus the following product gates where applicable: + +### Source and review + +- exact head/base state refetched; +- no valid unresolved review thread; +- qualifying independent non-author formal approval when required by current policy; +- no writer race or unexpected source mutation; +- dependency/lockfile changes intentional and reviewed. + +### Correctness and quality + +- repository contracts; +- formatting/static checks; +- all required tests; +- strict Clippy/rustdoc and other language quality checks; +- exact owned production 100% coverage under repository policy; +- real protocol/browser integration for shipped claims; +- hostile/security regressions; +- documentation graph consistent with shipped vs Planned/Proposed status. + +### Security + +- SAST/Semgrep/CodeQL or repository-required equivalent; +- dependency/OSV/vulnerability scans; +- supply-chain/Scorecard checks where configured; +- threat-model changes reviewed; +- no unresolved valid security finding; +- credential/PII leakage scans for applicable test corpus; +- pinned/verified security-sensitive actions/toolchains. + +### Compatibility + +For relevant releases: + +- supported Chromium build profile; +- WebDriver BiDi/CDP/MCP adapter conformance/version tests; +- Manifest V3 compatibility matrix; +- supported OS/hardware profiles; +- schema/API compatibility tests; +- migration/restore compatibility. + +### Operations + +- health/readiness/task-state acceptance; +- cancellation/recovery/quarantine path; +- observability and safe logging; +- backup/restore where persistence ships; +- release canary/rollback rehearsal; +- incident runbook links. + +## 5. Artifact production + +Release jobs produce artifacts from a clean immutable source checkout with pinned toolchain/dependencies. + +Required outputs, as applicable: + +- binaries/packages/container/distribution bundles; +- checksums; +- software bill of materials (**SBOM**) in a standard supported format; +- signed build/source **provenance** or attestations; +- license notices; +- compatibility manifest; +- configuration/schema versions; +- changelog/release notes; +- migration scripts and rollback/restore instructions. + +No artifact is accepted until its digest is independently recomputed and matched to the published manifest. + +## 6. Reproducibility + +The release process records: + +```text +release_version +source_commit_sha +toolchain_version +lockfile_digest +build_workflow_identity +build_runner/profile +artifact_digest +sbom_digest +provenance_digest +browser/chromium profile +protocol/schema versions +``` + +Every release artifact that OriginWeave itself builds must have reproducibility evidence for the artifact-generation step. When a platform requires nondeterministic signing or notarization, the reproducible artifact is generated and verified first; nondeterministic signing is a separate attested transformation bound to the verified pre-signing digest. A release is blocked when the reproducible artifact cannot be independently regenerated or otherwise proven byte-for-byte equivalent under its declared build profile. + +## 7. Signing and trust + +Release signing keys/identities are separate from ordinary PR write credentials. Build provenance identifies the source/ref/workflow and artifact digest. Consumer/operator documentation explains how to verify artifacts before deployment. + +Key compromise triggers release quarantine, key revocation/rotation, artifact impact analysis and replacement release according to incident policy. + +## 8. Release evidence bundle + +A release evidence bundle contains or references: + +- exact commit and tag; +- required check conclusions and run IDs; +- formal review evidence when policy requires it; +- test/coverage summaries; +- compatibility matrices; +- threat/security scan results; +- SBOM and dependency/license results; +- provenance/attestations; +- artifact digests/signatures; +- migration/rollback evidence; +- protected-main operational acceptance where required; +- known limitations/open risks. + +The bundle must be sufficient for an auditor/buyer to distinguish implementation evidence from roadmap prose. + +## 9. Canary strategy + +Production-capable releases use a bounded canary where deployment allows it. + +Observe at least: + +- process/session creation health; +- crash rate; +- task success and quarantine rate; +- stale-node/post-condition errors; +- destination/TLS/HTTP rejection drift; +- resource pressure/frame health; +- secret/PII leakage indicators; +- evidence/persistence integrity; +- extension/protocol compatibility regressions. + +Canary promotion is reversible; a canary problem does not lead to weakening a safety gate to make metrics green. + +## 10. Rollback triggers + +Examples: + +- security regression or provenance verification failure; +- cross-tenant/secret/PII exposure; +- unexpected privileged action; +- crash or data-integrity regression above the release profile threshold; +- browser/protocol incompatibility breaking supported critical workflows; +- evidence/provenance corruption; +- migration cannot satisfy integrity checks; +- resource governor regression threatening interactive safety. + +## 11. Rollback procedure + +General sequence: + +```text +stop promotion / unsafe new admission +-> preserve evidence and affected release identity +-> quarantine ambiguous tasks +-> select last verified compatible artifact +-> verify artifact digest/signature/provenance +-> evaluate data/schema backward compatibility +-> execute application rollback or restore/forward-fix plan +-> revalidate health + critical task suite +-> confirm tenant/session/evidence integrity +-> communicate incident and next action +``` + +Rollback never means restoring an artifact with a known critical vulnerability merely because it is operationally familiar; choose a safe forward fix or compensated migration when necessary. + +## 12. Database/schema rollback + +When durable storage exists, every migration is classified: + +- backward compatible / expand-contract; +- reversible transformation; +- irreversible destructive transformation; +- large/online migration requiring checkpointing. + +Before applying: + +- snapshot/backup/restore path tested; +- migration checksum/version recorded; +- tenant-impact and downtime estimated; +- rollback or forward-recovery steps defined; +- evidence/provenance data preserved. + +Irreversible destructive migrations require explicit release governance and cannot rely on “downgrade binary” as a rollback plan. + +## 13. Protocol/schema rollback + +OriginWeave Protocol and evidence schemas use version negotiation. A rollback must not cause a newer persisted/event schema to be silently interpreted under older semantics. + +Use: + +- explicit schema version; +- compatibility reader/writer where supported; +- dual-read/dual-write or translation window when required; +- rejection/quarantine when semantics are not safely compatible. + +## 14. Chromium rollback + +Browser rollback has security consequences. Before downgrading Chromium: + +- assess whether the prior build reintroduces a known security issue; +- verify OriginWeave adapter compatibility; +- verify profile/data compatibility; +- run critical MV3/session/action/observation tests; +- prefer forward fix when rollback would expose a patched high-severity vulnerability. + +## 15. Model/provider rollback + +Model routing/configuration is independently versioned from deterministic runtime authority. Rolling a model back requires its evaluation artifact and tenant/provider policy to remain valid. It does not require rolling back deterministic policy/network code unless the interface itself changed. + +## 16. Secret/config rollback + +Never restore revoked/expired secrets merely to recreate an old release. Configuration rollback validates current: + +- tenant policy; +- keys/certificates; +- origins/routes/trust roots; +- provider regions; +- retention rules; +- feature flags. + +Security configuration is current authority, not necessarily historical application state. + +## 17. Emergency release + +**Emergency releases do not bypass required gates.** A security emergency may shorten coordination cadence, but the same exact-source evidence requirements remain in force before publication. + +The emergency path must document and prove: + +- incident/vulnerability and exact smallest fix; +- current-head checks and every repository-required security scan; +- complete coverage and required rustdoc/static-quality gates; +- independent approval when current branch/repository policy requires it; +- branch protection/ruleset acceptance without administrative bypass; +- reproducible artifact generation plus separately attested nondeterministic signing when applicable; +- rollback/forward-fix plan and post-release verification. + +If a mandatory gate cannot run or produces non-passing evidence, the release remains blocked. OriginWeave automation has no authority to turn missing evidence into an emergency exception. + +## 18. Release notes truthfulness + +Release notes distinguish: + +- shipped Implemented capability; +- security/correctness fix; +- compatibility change; +- experimental/preview feature; +- deprecated behavior; +- Planned/Proposed work not included. + +Do not claim safe Chromium navigation, SOC 2/CSAP certification, complete extension compatibility or enterprise privacy controls before the corresponding exact release evidence exists. + +## 19. Post-release verification + +After publication/deployment: + +1. download/pull the public artifact through the consumer path; +2. verify digest/signature/provenance; +3. run smoke/critical task acceptance outside the source tree; +4. verify version/build metadata; +5. verify SBOM/provenance links; +6. confirm release notes/changelog match artifact; +7. monitor canary/production SLIs. + +A successful publish API response alone is not proof that the usable released artifact is correct. + +## 20. Release closure + +A release is closed only when: + +- artifact is publicly/privately available at the intended channel; +- artifact identity/provenance verifies; +- post-release smoke passes; +- rollback target/procedure remains available and verified; +- critical monitoring has no release-blocking regression; +- release evidence bundle is archived under policy; +- `CHANGELOG.md` and repository release metadata are correct. diff --git a/docs/TEST_STRATEGY.md b/docs/TEST_STRATEGY.md new file mode 100644 index 000000000..ba3c31624 --- /dev/null +++ b/docs/TEST_STRATEGY.md @@ -0,0 +1,354 @@ +# OriginWeave Test Strategy + +- **Status:** Proposed authoritative product test strategy +- **Product status:** Pre-alpha +- **Quality gates:** [`quality-gates.md`](quality-gates.md) +- **Threat model:** [`THREAT_MODEL.md`](THREAT_MODEL.md) +- **Technical requirements:** [`TRD.md`](TRD.md) + +## 1. Purpose + +OriginWeave tests are evidence for product claims. A test suite is not accepted merely because it has many cases or high line coverage; each material security, compatibility, authority, reliability and buyer-visible requirement must be exercised at the **true production boundary** where that requirement can fail. + +This document defines how tests progress from deterministic kernels to real browser/runtime acceptance without converting planned behavior into shipped claims. + +## 2. Non-negotiable quality contract + +For OriginWeave-owned production code: + +- exact production function/line/region/statement/branch coverage is **100%** where the repository's current tooling exposes the metric; +- public Rust APIs have useful rustdoc and public non-Rust APIs have complete docstrings; +- skipped/ignored required tests are not passing evidence; +- a test that rewrites production source or weakens a gate to pass is invalid evidence; +- failures are reproduced and fixed at the narrowest causal layer; +- release claims use exact protected-main/release-artifact evidence, not predecessor heads or synthetic merge results; +- new defects use red-green-refactor TDD when practical: first establish a realistic failing test, then implement the smallest coherent fix. + +Coverage is necessary but not sufficient. Generated, unreachable, exclusion-heavy or assertion-light coverage does not replace behavioral proof. + +## 3. Test pyramid by authority layer + +### 3.1 Pure value and policy contracts + +Use deterministic unit/property tests for: + +- canonical `Origin` and browser-special-host handling; +- action kinds, risk classes, capabilities and intent digests; +- approval scope and expiry; +- destination classification and resolution snapshots; +- route/proxy authority values; +- resource budgets and cumulative mitigation decisions; +- evidence locator/digest/value-redaction rules. + +### 3.2 Stateful boundary tests + +Use deterministic state-transition and concurrency tests for: + +- document/session/context/node lifetime; +- retry classification and attempt accounting; +- secret-handle issue/use/revoke/expiry lifecycle; +- idempotency/cancellation/checkpoint semantics; +- tenant/task/profile isolation; +- resource admission and mitigation sequencing. + +### 3.3 Real protocol integration + +Use loopback or hermetic real implementations, not mocks alone, for: + +- TCP connection and `peer_addr` evidence; +- rustls/WebPKI certificate identity; +- bounded HTTP framing/content/deadline behavior; +- proxy/PAC execution once implemented; +- browser adapter transport where a safe local target can prove the real path. + +### 3.4 Browser vertical slices + +Once the browser/session/action adapter exists, run a real supported Chromium build/profile against deterministic hostile and normal local sites. Required flows include: + +```text +session creation +-> isolated context +-> navigation +-> semantic observation +-> node selection +-> action policy +-> typed action +-> observed post-condition +-> evidence export +-> task close/recovery +``` + +### 3.5 Buyer acceptance + +Versioned task packs measure repeatable product outcomes rather than one lucky agent run. The benchmark artifact records browser build, OriginWeave version, model/provider/reasoning configuration, seed where supported, policy profile, hardware profile and source fixtures. + +## 4. Authority-specific tests + +### 4.1 Origin / destination + +Include: + +- malformed/ambiguous URLs and Unicode host forms; +- IPv4 integer/hex/octal-looking variants; +- IPv4-mapped IPv6; +- private/link-local/metadata/platform/reserved/documentation/benchmark ranges; +- empty/oversized resolver answer; +- hostname/IP/localhost origin constraints; +- DNS contraction vs expansion/rebinding; +- redirect downgrade, cycle, hop limit and new destination authorization. + +### 4.2 Route / TCP + +Include direct-only default, unauthorized proxy/PAC origin, PAC-selected DIRECT vs proxy authority, exact address set membership, port/timeout/attempt bounds, permission/input/address errors, transient retry allow-list, exact peer mismatch and single-use plan replay. + +### 4.3 TLS + +Use real loopback certificates/roots for: + +- correct/wrong DNS SAN; +- Common Name fallback rejection; +- correct/wrong IPv4/IPv6 SAN; +- trusted/untrusted roots; +- not-yet-valid/expired/fixed trusted time; +- TLS 1.2/TLS 1.3; +- allowed/required/absent ALPN; +- transport-origin mismatch; +- peer mutation/inspection failure; +- certificate/trust/ALPN/deadline bounds; +- task-horizon safety policy if shipped. + +### 4.4 HTTP + +When protected-main HTTP capability exists, tests include: + +- valid Content-Length, chunked and close-delimited responses; +- HEAD and no-body status semantics; +- conflicting/malformed Content-Length; +- Transfer-Encoding + Content-Length ambiguity; +- invalid status/header syntax/obs-fold/whitespace; +- incomplete/premature EOF; +- chunk/trailer limits; +- gzip/deflate expansion ratio; +- total exchange deadline; +- digest field valid/absent/malformed/unsupported/mismatch; +- supplied/observed MIME and nosniff behavior; +- safe/unsafe Content-Disposition names; +- redirect returned as evidence without ambient follow. + +### 4.5 Browser session, observation and action + +When shipped, tests include: + +- nonzero opaque session/context IDs; +- same local node ID in two sessions/contexts; +- same origin+epoch in two contexts; +- navigation/replace rotates document epoch; +- stale handle rejected before input dispatch; +- iframe/shadow DOM/virtualized interface behavior where supported; +- accessible vs hidden text and source-channel disagreement; +- typed click/input/select/scroll/download/upload actions; +- post-condition pass/fail/timeout; +- cross-origin action decomposition; +- browser crash and context recovery. + +## 5. Hostile-input strategy + +Every parser and boundary that accepts attacker-controlled bytes receives table-driven negatives, property tests and fuzzing where practical. + +Hostile classes include: + +- control/NUL/invalid UTF-8/hostile Unicode and bidi controls; +- enormous count/length/nesting values; +- percent-encoding ambiguity and encoded separators; +- duplicate singleton fields; +- path traversal/device names; +- protocol smuggling/framing ambiguity; +- malformed certificates/HTTP fields/JSON/protocol messages; +- prompt injection in visible, hidden, metadata, structured, tool and visual channels; +- poisoned provenance locators/digests; +- replay/stale/race sequences; +- hostile extension messages; +- cross-tenant identifier collision. + +A hostile test must assert the safe failure/result, not merely that the process does not crash. + +## 6. Prompt-injection and LLM tests + +Model behavior is nondeterministic evidence and must be surrounded by deterministic assertions. + +### Offline contracts + +Test that: + +- untrusted page text cannot directly become a policy instruction; +- model output schema rejects untyped/arbitrary actions; +- secret values are absent from model-bound payloads; +- capability/origin/risk/approval gates are evaluated after model proposal; +- model result cannot mark an unobserved post-condition successful. + +### Live smoke + +Live LLM tests use `NVIDIA_NIM_API_KEY` through the reviewed credential boundary, preferably `contextual-orchestrator`. `COPILOT_GITHUB_TOKEN` is not used. Provider/model/reasoning/prompt hashes are recorded. Provider outages/rate limits are distinguished from product correctness failures. + +### Evaluation + +Use multiple prompt-injection variants, repeat runs and outcome distributions rather than a single success. Measure unauthorized-action rate, injection success rate, abstention/fail-closed rate and unsupported-claim rate. + +## 7. Secret / PII tests + +Use synthetic values unique enough for exact byte-occurrence scanning. + +A representative sensitive flow must prove the approved value is usable where the business task requires it while absent from: + +- model input/output unless selectively authorized; +- application logs; +- exceptions/errors; +- traces and metric labels; +- screenshots/AX labels unless explicitly necessary and policy-approved; +- generic WARC/PROV evidence; +- support/crash bundles; +- URLs/query strings; +- clipboard/history where not explicitly required. + +Test wrong tenant/task/field/purpose/origin/audience, expired/revoked handle, max-use/replay, concurrent-use race, break-glass lifecycle and provider-region mismatch. + +## 8. Resource and performance tests + +### 8.1 Deterministic governor + +Property tests cover exact soft/hard boundaries and cumulative simultaneous pressures. + +### 8.2 Platform acceptance + +On declared hardware profiles measure: + +- foreground input latency; +- frame/compositor time and dropped frames; +- tab/process/task peak RSS; +- semantic snapshot/diff bytes; +- CPU-worker use/context switches where observable; +- peak VRAM/model residency; +- model batch/offload/CPU fallback; +- network/TLS/HTTP timing; +- task throughput and queue depth. + +A resource test must prove the active offending consumer is reduced/paused and new admission is rejected at hard limits; merely preventing future work is insufficient. + +## 9. Extension compatibility tests + +For each supported Chromium release profile, verify representative Manifest V3 behavior: + +- install/update; +- extension service-worker restart; +- content scripts and scripting; +- storage; +- declarativeNetRequest; +- downloads; +- native messaging where supported; +- side panel/commands; +- browser restart persistence; +- task-mode isolation and separate OriginWeave agent grants. + +Compatibility is a versioned matrix, not a claim that every Chrome extension works. + +## 10. Protocol interoperability tests + +WebDriver BiDi, CDP, WebMCP and MCP adapters require: + +- supported-version declaration; +- schema/message validation at the process boundary; +- unknown/extra/oversized input tests; +- identifier translation/lifetime tests; +- cancellation/timeouts; +- adapter crash/restart behavior; +- conformance tests from the primary standard/project where usable; +- proof that protocol permissions do not bypass OriginWeave authority. + +## 11. Persistence, provenance and data tests + +When persistence adapters ship: + +- write/read round-trip every versioned record; +- enforce two-word `snake_case` database naming; +- tenant/task authorization before access; +- object/WARC/PROV digest consistency; +- retention/deletion/legal-hold transitions; +- backup/restore and migration compatibility; +- provenance completeness from result to source/action/policy/post-condition; +- tamper/corruption detection; +- no raw secret in general evidence tables/artifacts. + +## 12. Concurrency and race tests + +Required race classes include: + +- navigation between observation and action; +- two actions using the same one-use handle; +- concurrent secret revocation/use; +- browser context close during action; +- resource pressure while task admission changes; +- cancellation during network/model/action execution; +- retry after ambiguous external side effect; +- multiple tenant sessions sharing process infrastructure; +- repository writer changing exact PR head during review/check/merge decisions. + +Use deterministic barriers/latches/fakes for race orchestration, then real integration stress where practical. + +## 13. Release and protected-main acceptance + +A feature PR being green is not a release proof. Before a release: + +1. verify exact protected-main SHA and generated artifact identity; +2. run required CI/SAST/security/coverage/packaging gates; +3. run supported browser/protocol/extension compatibility profiles; +4. run required product vertical-slice and hostile suites; +5. run protected-main operational acceptance for scheduler/runtime fixes; +6. verify SBOM/provenance/reproducibility/rollback artifacts; +7. verify no required check is queued, pending, skipped, cancelled, neutral, absent, failed or predecessor-head only; +8. verify qualifying independent review where policy requires it. + +The phrase **protected-main** appears in evidence reports so release claims can be distinguished from branch-local evidence. + +## 14. Failure triage and RCA + +For every unexpected failure: + +```text +exact evidence +-> first failing boundary +-> minimal reproduction +-> falsifiable root-cause hypothesis +-> materially distinct remedy candidates +-> feasibility check +-> smallest safe fix +-> rerun exact failure +-> affected full gates +``` + +Do not retry deterministic failures blindly. If multiple distinct fixes fail, reassess the architecture/contract rather than stacking speculative patches. + +## 15. Test-data governance + +- Prefer generated/synthetic data for secrets and PII. +- Real third-party sites are not mutated without authorization. +- Browser fixtures are versioned and reproducible. +- Public benchmark licenses/terms are recorded. +- Production user data is not copied into repository fixtures. +- Test artifacts follow retention and evidence rules. + +## 16. Documentation evidence + +Documentation contracts intentionally validate only durable properties such as required files, links, status vocabularies and authority assertions. Do not create brittle tests that freeze wording without preventing a real documentation defect. + +## 17. Exit criteria for a production capability + +A capability may be documented as Implemented only when: + +- the production code is on protected `main`; +- realistic positive/negative/security tests pass; +- owned production coverage is 100% under repository policy; +- public documentation is complete; +- governing ADR/PRD/TRD/architecture/traceability are consistent; +- degraded and error behavior is tested; +- the real integration path, not a mock-only path, has acceptance evidence; +- no known valid security/review finding remains unresolved. diff --git a/docs/THREAT_MODEL.md b/docs/THREAT_MODEL.md new file mode 100644 index 000000000..419423032 --- /dev/null +++ b/docs/THREAT_MODEL.md @@ -0,0 +1,233 @@ +# OriginWeave Threat Model + +- **Status:** Proposed authoritative product threat model +- **Product status:** Pre-alpha +- **Security policy:** [`../SECURITY.md`](../SECURITY.md) +- **Technical requirements:** [`TRD.md`](TRD.md) +- **Architecture:** [`../ARCHITECTURE.md`](../ARCHITECTURE.md) +- **Evidence/standards:** [`doctoring.md`](doctoring.md) + +## 1. Purpose + +OriginWeave assumes the web, browser renderers, model outputs, downloaded content, external agent frameworks, and many integration inputs may be hostile. This threat model identifies assets, trust boundaries, attacker goals, product security properties, and required validation evidence. It is an engineering threat model, not a claim of certification or legal compliance. + +## 2. Security objectives + +OriginWeave must preserve all of the following properties even when one lower-trust component misbehaves: + +1. untrusted web content cannot become trusted instruction authority; +2. a logical origin grant cannot silently expand into unrelated resolved addresses, proxy routes, TCP peers, TLS identities, or redirects; +3. a model cannot create capabilities, approvals, secrets, destination authority, or successful outcomes by assertion; +4. raw secrets and protected personal values do not enter model-visible observations, generic logs, traces, evidence, or provenance; +5. a node observed in one session/context/document cannot be reused as authority in another; +6. state-changing actions require the right capability, origin, risk/approval and current authority immediately before execution; +7. action success requires an observed post-condition; +8. resource exhaustion by agent/model work cannot take priority over interactive safety; +9. tenant or task authority cannot cross a boundary because two objects share an identifier, cache, browser profile, queue, connection, model session, or storage backend; +10. evidence remains sufficient to reconstruct what was authorized, attempted, observed and derived without becoming a new secret store. + +## 3. Trust zones + +### Zone A — Human and enterprise authority + +Contains the authenticated human goal, managed enterprise policy, explicit approvals, tenant configuration and operator break-glass decisions. These are trusted only after identity/session/policy validation; a UI string alone is not authority. + +### Zone B — OriginWeave trusted Rust control plane + +Contains deterministic policy, canonical origin/destination/route/transport/TLS/HTTP authority, session/node lifetime validation, resource governance, secret brokerage and evidence assembly. Compromise of this zone is a critical product compromise. + +### Zone C — Chromium browser process and privileged adapters + +Contains trusted browser integration code that translates Chromium/WebDriver/CDP state into OriginWeave contracts and dispatches approved actions. It must validate all renderer-originated or external-protocol messages before converting them into trusted values. + +### Zone D — Renderer / web content + +Explicitly hostile. **renderer compromise** is in scope. Site Isolation and Chromium sandboxing reduce blast radius but are not substitutes for Rust-side validation. + +### Zone E — Model and orchestration providers + +Model outputs are proposals/data, not authority. Providers may be unavailable, stale, compromised, prompt-injected, or configured incorrectly. External orchestration is not allowed to bypass OriginWeave policy or secret boundaries. + +### Zone F — Persistence and evidence adapters + +Relational, object, WARC, PROV and telemetry systems may have separate operational trust. Each adapter receives only the minimum data authorized by its schema and tenant/purpose contract. + +### Zone G — External web and enterprise services + +Remote sites, proxies, DNS resolvers, PAC sources, model providers, connectors and APIs may be malicious or compromised. Their identities and data require explicit validation at the applicable boundary. + +## 4. Assets + +| Asset | Why it matters | +|---|---| +| user/enterprise goal and approvals | source of legitimate task authority | +| browser profile/session state | cookies, history, identity and delegated context | +| secret/protected-value store | credentials and operational PII | +| origin/destination/route/TCP/TLS/HTTP authority | prevents SSRF, route confusion and service impersonation | +| semantic observation and node authority | prevents stale/cross-context browser actions | +| resource budgets | protects human interaction and host stability | +| action/post-condition evidence | distinguishes attempt from actual outcome | +| provenance/source artifacts | supports audit and buyer-visible proof | +| tenant policy and residency/retention policy | prevents cross-tenant or out-of-policy disclosure | +| release artifact, SBOM and provenance | prevents supply-chain substitution | + +## 5. Threat actors + +- malicious web page or compromised origin; +- compromised renderer process; +- malicious/compromised browser extension; +- prompt-injected page/tool/download/email-like content; +- malicious or compromised model/provider; +- malicious external MCP/BiDi/CDP client; +- tenant user attempting privilege escalation; +- insider/support/operator abusing privileged access; +- compromised dependency, build action or release pipeline; +- network attacker or malicious DNS/proxy/PAC infrastructure; +- confused deputy using a legitimately privileged service for an unauthorized destination or tenant; +- availability attacker causing CPU/RAM/VRAM/network/task-queue exhaustion. + +## 6. Major threat scenarios and controls + +### TM-001 — Indirect prompt injection + +**Attack:** page text, hidden content, WebMCP output or downloaded text tells the model to ignore the user goal, exfiltrate cookies, expand the task or invoke unsafe tools. + +**Controls:** + +- `trusted_instruction`, `untrusted_observation` and `protected_secret` remain separate types/channels; +- page/model content cannot modify deterministic policy or capability sets; +- model receives bounded typed observations rather than ambient raw browser state; +- high-risk actions are re-evaluated by deterministic policy immediately before execution; +- secret values are absent from model context; +- regression corpus includes visible/hidden/multilingual/encoded injection variants. + +### TM-002 — SSRF / destination confusion + +**Attack:** a public-looking hostname resolves to private, link-local, metadata or platform endpoints; DNS later expands to an unapproved address; redirect changes authority. + +**Controls:** implemented destination classification, explicit class grants, origin-bound resolution snapshots, canonical IPv4-mapped handling, non-expanding revalidation and per-hop redirect authorization. + +### TM-003 — Route/proxy/PAC bypass + +**Attack:** ambient proxy environment, a malicious PAC source or unreviewed proxy selection changes the real intermediary and bypasses the direct-route security assumptions. + +**Controls:** route authority is explicit; direct is default; PAC source and selected proxy require independent approval; proxy execution must not infer authority from environment variables or from final-target origin permission. + +### TM-004 — TCP/TLS identity confusion + +**Attack:** connecting to an approved IP is treated as authenticating the requested HTTPS service, or a TLS implementation reconnects/resolves behind the policy layer. + +**Controls:** exact `peer_addr` verification precedes stream exposure; TLS consumes that same stream; reference identity derives only from canonical HTTPS origin; explicit roots/time/SAN validation; no TLS reconnect/resolution. + +### TM-005 — HTTP framing and content ambiguity + +**Attack:** request/response smuggling, conflicting framing, compression bomb, malformed trailers, MIME confusion, unsafe filenames or redirects cause a different semantic result than the policy reviewed. + +**Controls:** bounded HTTP authority is an independent layer with strict framing, byte/count/deadline limits, integrity/MIME/disposition evidence and no automatic redirect follow. This layer is active development and must not be claimed as protected-main capability until merged. + +### TM-006 — Stale or cross-context node reuse + +**Attack:** an adapter-local node ID collides across sessions, frames, origins or documents; an agent acts on stale UI after navigation. + +**Implemented controls:** `originweave-core` already binds `ObservedNodeHandle` to OriginWeave browser-session, browsing-context, canonical-origin, document-epoch and adapter-local-node identities and exposes deterministic validation for cross-session, cross-context, cross-origin and stale-document reuse. These contracts are covered by the current core tests and remain observation-authority primitives rather than proof of a live Chromium dispatch path. + +**Planned controls:** the browser adapter must rotate the document epoch for relevant same-document DOM/accessibility mutations, revalidate the same handle authority at the action linearization point immediately before the trusted side effect, abort on any competing mutation, and require re-observation before a new action can proceed. The first real Chromium vertical slice must prove that a pre-mutation handle is rejected while the newly observed handle succeeds. + +### TM-007 — Secret/PII exfiltration + +**Attack:** password, token or operational PII is placed in prompt text, accessibility labels, logs, traces, screenshots, provenance, support bundle or an unauthorized connector/model. + +**Controls:** opaque handles by default; purpose/field/destination/classification authority; trusted broker; field-level disclosure; provider/region/retention policy; generic evidence value-redaction; no blanket assumption that PII can be safely copied because a service is internal. + +### TM-008 — Sensitive-handle replay and race + +**Attack:** a handle is replayed, transferred to another task/tenant, used concurrently beyond its maximum count, or resolved after expiry/revocation. + +**Controls:** planned broker owns trusted time, atomic use reservation, audience/task/tenant/field/destination scope, max-use enforcement, expiry/revocation and compensation semantics. Model-side counters are not trusted. + +### TM-009 — Confused deputy + +**Attack:** a service with legitimate access is asked to fill/send data to an unauthorized origin, tenant, model or connector. + +**Controls:** **confused deputy** checks bind actor/workload identity, task, tenant, field, business purpose, destination and action; service possession of a credential does not grant downstream disclosure authority. + +### TM-010 — Cross-tenant contamination + +**Attack:** profile/session/cache/queue/model context/object-store/vector/evidence identifiers allow one tenant to read or act on another tenant's data. + +**Controls:** all persistent/runtime authority is tenant/task scoped; no global singleton as authority; cache keys include security scope; **cross-tenant** tests cover concurrent sessions, shared infrastructure and support operations; enterprise adapters remain Planned until these proofs exist. + +### TM-011 — Malicious/compromised extension + +**Attack:** an MV3 extension observes sensitive task state or injects behavior that the agent interprets as user intent. + +**Controls:** preserve Chromium extension sandbox/permission model; extension access to OriginWeave agent authority requires a separate signed policy grant; extension data remains untrusted observation; compatibility tests include task-mode isolation. + +### TM-012 — Resource exhaustion + +**Attack:** page, model or task drives unbounded DOM snapshot, response body, decompression, screenshot, CPU worker, RAM or VRAM consumption and makes the browser unusable. + +**Controls:** boundary-specific byte/count/deadline limits; deterministic resource budget; human/compositor priority; cumulative mitigations; model batch/cache reduction; CPU fallback; pause/reject admission at hard limits. + +### TM-013 — Evidence poisoning / provenance forgery + +**Attack:** attacker supplies source URLs, locators, timestamps or hashes that make a fabricated result appear verified. + +**Controls:** source locators are parsed/validated, digests computed inside trusted boundaries, generic values redacted, model claims separated from deterministic verification, trusted time used for authoritative lifecycle decisions, provenance links carry verification state. + +### TM-014 — Supply-chain compromise + +**Attack:** dependency/action/toolchain/release artifact is substituted or a mutable external action executes unexpected code. + +**Controls:** lock dependencies/toolchains, pin security-sensitive actions, SBOM, signed/provenanced releases, dependency/security scanning, artifact verification, reproducible-build evidence where supported, protected-branch review. + +### TM-015 — Approval spoofing / governance bypass + +**Attack:** comment/status/model output/self-review is treated as qualifying approval, or pending/old checks are treated as current success. + +**Controls:** exact current head/base evidence, formal review-state validation when policy requires a counted review, reviewer eligibility, unresolved-thread checks, no synthetic approval, no old-head check promotion, separate publication and merge authority. + +### TM-016 — Operator/support abuse + +**Attack:** privileged operator silently accesses profiles, raw secrets or tenant evidence. + +**Controls:** least privilege, separate support capability, explicit **break-glass** workflow, reason/time limit/approval, heightened audit and post-event review. Full enterprise operation is Planned. + +## 7. STRIDE-oriented summary + +| STRIDE | OriginWeave examples | Principal mitigation | +|---|---|---| +| Spoofing | TLS service, reviewer, tenant/workload identity | explicit identity + exact evidence | +| Tampering | page/tool output, provenance, redirect, artifact | validation, digests, immutable evidence, protected release | +| Repudiation | agent/action/approval disputes | intent-bound approval + action/post-condition evidence | +| Information disclosure | secrets, PII, headers, screenshots | opaque handles, purpose-bound disclosure, redaction | +| Denial of service | decompression, DOM, GPU/model pressure | byte/count/time/resource budgets | +| Elevation of privilege | prompt injection, extension, confused deputy | typed authority, deterministic policy, tenant/task scope | + +## 8. Security acceptance evidence + +Before a production release, security evidence must include at least: + +- hostile origin/URL/DNS/redirect/proxy/TCP/TLS/HTTP test suites for every shipped boundary; +- prompt-injection regression across structured, DOM, hidden and visual inputs; +- stale/cross-session/cross-context node tests for shipped observation/action adapters; +- secret/PII byte-occurrence scanning across logs, traces, errors, screenshots, WARC/PROV and model requests for the approved test corpus; +- tenant-isolation concurrency tests; +- resource exhaustion and recovery tests; +- extension compatibility/isolation tests for supported APIs; +- dependency/SAST/security scans on the exact release head; +- SBOM/provenance/reproducibility/rollback evidence; +- a review of any Accepted ADR that changes a trust boundary. + +## 9. Residual and open risks + +- **Open:** real Chromium navigation has not yet proven end-to-end consumption of every Rust authority layer. +- **Open:** complete proxy/PAC and bounded HTTP integration is not yet protected-main behavior in this baseline. +- **Open:** opaque sensitive-data broker persistence/atomic lifecycle is not yet complete protected-main behavior. +- **Open:** enterprise tenant/SSO/SCIM/residency/support controls are not shipped. +- **Open:** WebMCP is experimental upstream and must remain optional/versioned. +- **Open:** product UI and extension compatibility matrices require release-specific evidence. + +## 10. Change control + +Any protected change that introduces a new trust zone, privileged IPC/protocol, secret/PII path, persistence class, tenant boundary, browser authority, external model/provider, release authority or executable content channel must update this threat model and the governing ADR/TRD in the same reviewed change or an explicit prerequisite. diff --git a/docs/TRD.md b/docs/TRD.md new file mode 100644 index 000000000..7330fec98 --- /dev/null +++ b/docs/TRD.md @@ -0,0 +1,485 @@ +# OriginWeave Technical Requirements Document + +- **Document status:** Proposed authoritative technical baseline +- **Product status:** Pre-alpha +- **Product requirements:** [`PRD.md`](PRD.md) +- **Canonical system architecture:** [`../ARCHITECTURE.md`](../ARCHITECTURE.md) +- **Architecture decisions:** [`adr/README.md`](adr/README.md) +- **Research and standards:** [`doctoring.md`](doctoring.md) + +## 1. Purpose and truth model + +This TRD defines technical invariants for OriginWeave without describing planned modules as shipped. The implementation-status vocabulary is: + +- **Implemented** — present on protected `main` with executable repository evidence. +- **Accepted architecture** — binding design direction represented by reviewed architecture/ADR material, while complete adapters may remain absent. +- **Planned** — roadmap work that has not reached protected `main`. +- **Proposed** — a candidate design that still needs a dedicated reviewed decision or implementation proof. +- **Open** — deliberately unresolved. + +Pull-request code is not treated as Implemented until it reaches protected `main` and required acceptance evidence is re-established there. + +## 2. Current protected-main implementation inventory + +The current reusable Rust control plane is intentionally smaller than the final browser product. + +| Module | Current responsibility | Status | +|---|---|---| +| `originweave-core` | Canonical origin, typed actions, purpose/mode, capabilities, risk, secret-delivery and approval contracts. | **Implemented** | +| `originweave-policy` | Pure fail-closed action-policy evaluation. | **Implemented** | +| `originweave-destination` | Resolved-address classification, origin-bound snapshots, connection pinning, rebinding and redirect authority. | **Implemented** | +| `originweave-network` | Direct single-address TCP connection plan and exact operating-system peer verification. | **Implemented** | +| `originweave-tls` | WebPKI service identity over the already verified TCP stream. | **Implemented** | +| `originweave-resource` | Deterministic resource budgets and cumulative mitigation plans. | **Implemented** | +| `originweave-evidence` | Value-redacted network evidence and provenance foundations. | **Implemented** | +| Browser/session/observation/action adapters | Chromium/BiDi/CDP integration and node-lifetime enforcement. | **Planned / active development** | +| HTTP/proxy/PAC execution | Bounded HTTP and explicit route execution beyond pure foundations. | **Planned / active development** | +| Secret broker persistence/runtime | Atomic opaque-handle lifecycle and trusted fill. | **Planned / active development** | +| WARC/PROV persistence | Durable capture and provenance serialization. | **Planned** | + +## 3. Architectural invariants + +### TRD-INV-001 — Chromium compatibility kernel + +**Accepted architecture.** Blink, V8, Skia, Viz, Dawn/WebGPU, Site Isolation, sandboxing, and the Manifest V3 extension runtime remain Chromium/upstream responsibilities. OriginWeave adds Rust control-plane behavior through narrow adapters or service boundaries. + +### TRD-INV-002 — Explicit authority dimensions + +The following authorities are separate and may not be inferred from one another: + +```text +user / enterprise goal +-> task purpose +-> browser session and browsing context +-> typed action capability +-> logical origin +-> resolved destination +-> proxy/PAC route authority +-> exact TCP peer +-> TLS service identity +-> bounded HTTP semantics +-> document epoch + observed node authority +-> sensitive-data / secret authority +-> risk-specific approval +-> observed post-condition +-> evidence/provenance +``` + +A **logical origin** is not a **resolved destination** decision. A resolved address approval is not a **TCP peer** proof. A verified TCP peer is not **TLS service identity**. TLS identity is not an HTTP body/resource-budget decision. A valid node handle is not action capability. A policy decision is not evidence that execution succeeded. + +### TRD-INV-003 — Untrusted page content + +Browser content, rendered text, hidden text, comments, ads, WebMCP output, network bodies, downloads, and model-produced summaries are data. They cannot mutate system policy, expand capabilities, authorize destinations, reveal secrets, or redefine the user's goal. + +### TRD-INV-004 — Secret separation + +Raw credentials and protected values do not enter LLM prompts or untrusted observation channels. Model-visible values are opaque handles or independently safe derived values. Trusted resolution/fill occurs outside model context. + +### TRD-INV-005 — Observe/verify action lifecycle + +A typed action may be attempted only after exact current authority is validated. Success requires an observed post-condition. Adapter return without the expected state transition is failure or uncertainty, not success. + +## 4. Execution-mode requirements + +### Human Mode + +**Accepted architecture.** Autonomous control is denied unless the human explicitly transitions or delegates into another governed mode. Human input/rendering priority is highest. + +### Assist Mode + +**Accepted architecture; Planned adapter path.** Reversible/read behavior may be automated. Irreversible or externally visible state changes re-enter the risk/approval pipeline. + +### Agent Task Mode + +**Accepted architecture; Planned adapter path.** Each delegated task receives an isolated or explicitly attached browser context, scoped capabilities, origins, secrets, policy and resource budgets. The unrestricted default human profile is not ambient task authority. + +### Crawler Mode + +**Accepted architecture; policy foundation Implemented.** Crawler actions are read-only. Robots evidence, rate controls, purpose, privacy, retention and legal/contract policy are distinct checks. + +## 5. Identifier and lifetime contracts + +### 5.1 Core identifiers + +Durable identifiers introduced by adapters must be opaque and nonzero/nonempty. External browser identifiers are translated through scoped registries instead of becoming the core authority value directly. + +Planned browser-lifetime tuple: + +```text +browser_session_id ++ browsing_context_id ++ canonical_origin ++ document_epoch ++ adapter_local_node_id +``` + +An actionable node reference is valid only when every component matches the live task context immediately before use. + +### 5.2 Document epochs + +Navigation, document replacement, or another adapter-defined actionable-document lifetime change rotates `document_epoch`. A stale node reference must fail deterministically before input dispatch. + +### 5.3 Idempotency + +Commands that can be replayed through retries or operator recovery require explicit idempotency semantics. Idempotency keys are scoped at least by tenant/task/action contract and cannot turn a semantically different action into the same request. + +## 6. Network authority stack + +### 6.1 Origin + +**Implemented.** Canonical origin parsing follows browser-compatible host semantics and rejects dangerous ambiguous numeric-host forms. The origin represents logical web identity only. + +### 6.2 Resolution and destination classification + +**Implemented.** A trusted adapter supplies a nonempty bounded resolver result. The destination kernel: + +- canonicalizes IPv4-mapped IPv6 before classification; +- applies reviewed special-purpose/platform endpoint rules; +- binds approved addresses to the origin; +- requires connection candidates to belong to the approved set; +- permits nonempty DNS contraction; +- rejects newly introduced addresses as possible rebinding; +- reauthorizes redirect targets independently. + +The pure destination crate itself does no DNS lookup. + +### 6.3 Route/proxy authority + +**Accepted architecture; active development.** Direct routing is the default. Proxy and PAC-selected routes require explicit authority. A proxy is an intermediate authority and never replaces final-target authorization. Ambient environment proxy variables cannot silently change the governed route. + +### 6.4 Direct transport + +**Implemented.** `originweave-network` receives an exact authorized canonical socket, applies bounded attempt/timeout policy, connects to that address, and verifies `peer_addr` before exposing the stream. It performs no hostname re-resolution and does not authenticate HTTPS identity. + +### 6.5 TLS service identity + +**Implemented.** `originweave-tls` consumes the exact verified stream. Reference identity comes only from the canonical HTTPS origin. DNS identities require `dNSName` SAN; IP literals require exact `iPAddress` SAN; Common Name fallback is prohibited. Trust roots and verification time are explicit. The first slice permits TLS 1.3 and TLS 1.2, disables early data/resumption/key logging/secret extraction/client certificates/dangerous custom verifiers, and records bounded credential-free evidence. + +### 6.6 HTTP semantics + +**Accepted architecture; active development.** HTTP processing must consume an authenticated governed connection and define: + +- supported methods and caller-controlled fields; +- syntax/framing rules; +- header, trailer, chunk, decoded-body and elapsed-time budgets; +- digest/integrity handling; +- MIME and content-disposition interpretation; +- redirect metadata and per-hop reauthorization; +- download byte and persistence gates; +- connection-reuse authority if later introduced. + +No HTTP adapter may reconnect by hostname behind the authority stack without a new authorization path. + +### 6.7 Browser network integration + +**Planned and release-critical.** Safe navigation is not a supported claim until the real Chromium/browser adapter demonstrates that its real network path consumes the governed resolution, route, transport, TLS and HTTP authorities without an alternate ambient connection path. + +## 7. Observation architecture + +Observation order is an **Accepted architecture** requirement: + +1. site-provided typed tool / WebMCP when present and policy-allowed; +2. JSON-LD, Microdata, RDFa, Open Graph, HTML table/form/link and ARIA structure; +3. bounded, authorized network data; +4. Accessibility tree + DOM + layout; +5. screenshot/vision fallback for canvas, remote-desktop, image-only or semantically inaccessible UI. + +Raw HTML is not the default model payload. + +### 7.1 Semantic snapshot + +**Planned.** A semantic snapshot includes bounded node identity, role, accessible name, state, canonical origin, visibility/layout evidence, available typed actions and source channels. It must not include raw credentials or unrestricted network headers. + +### 7.2 Incremental observation + +**Planned.** After a full snapshot, subsequent updates use bounded semantic diffs where possible. Observation cache use is included in task resource accounting. + +### 7.3 Source disagreement + +**Planned.** If accessibility, DOM/layout, structured data, network data and visual evidence disagree materially, evidence records the disagreement; the runtime does not silently select the most convenient interpretation. + +## 8. Action architecture + +Standard action vocabulary is **Accepted architecture / Planned runtime integration**: + +```text +navigate +go_back +query_nodes +click_node +type_text +fill_secret +select_option +set_checkbox +scroll_container +wait_for_state +download_resource +upload_approved_file +extract_schema +capture_evidence +``` + +Arbitrary script execution is outside the standard production interface. + +### 8.1 Pre-execution checks + +Immediately before a state-changing action, validate: + +- session mode and purpose; +- exact task/action capability; +- node/session/context/origin/document lifetime when a node is used; +- current destination/route/service authority if network activity is implied; +- sensitive-data scope and secret-handle authority; +- risk class and exact current approval evidence; +- resource/admission state. + +### 8.2 Post-condition + +The adapter declares an observable post-condition contract, such as URL change, dialog appearance, field state, download evidence or bounded network mutation. Failure to observe it is not success. + +## 9. Sensitive-data and secret requirements + +### 9.1 Purpose-bound authority + +**Active development.** Protected disclosure authority is represented as one value object/scoped record containing tenant, task, field, business purpose, canonical destination and data classification. Reclassification requires newly valid authority. + +### 9.2 Opaque handle broker + +**Planned.** The broker, not the model, owns: + +- trusted time; +- caller-unforgeable handle state; +- atomic use reservation/increment; +- maximum-use enforcement; +- expiry/revocation; +- concurrent and replay protection; +- value resolution/fill; +- compensation/recovery after reserved-but-failed use. + +### 9.3 Evidence + +Access/disclosure evidence records identifiers, scope, decision, approval reference, policy version and lifecycle times without carrying the protected value. + +## 10. Resource-governor requirements + +### 10.1 Deterministic kernel + +**Implemented foundation.** `originweave-resource` validates budgets and produces a cumulative mitigation plan. It does not sample the operating system or directly schedule processes. + +### 10.2 Adapter telemetry + +**Planned.** Platform adapters supply bounded observations for process/task RSS, JS heap, observation cache, frame time, GPU/VRAM use, model residency, batch size and CPU-worker use. + +### 10.3 Priority order + +**Accepted architecture.** Human interaction and compositor/foreground browser health outrank autonomous inference and background capture. + +### 10.4 Constrained GPU + +**Accepted architecture / Planned implementation.** Rendering and local model inference use phase scheduling where necessary. The mitigation ladder can shrink model batches, release inference caches, offload to CPU, pause the task and reject admission before foreground rendering is sacrificed. + +## 11. Evidence and provenance requirements + +### 11.1 Evidence identity + +Evidence must record the exact authority/result it proves rather than collapse multiple authorities into one green boolean. Examples: + +```text +origin_authority +resolution_evidence +route_evidence +connection_evidence +tls_identity_evidence +http_exchange_evidence +observation_evidence +policy_decision +action_event +post_condition_evidence +provenance_record +``` + +### 11.2 Data minimization + +Generic network evidence retains bounded names and canonical locators while values are universally redacted unless a separate schema-specific capture contract authorizes typed values. + +### 11.3 Durable adapters + +**Planned.** WARC-compatible source capture, relational metadata, object artifacts, and PROV-compatible derivation are independent adapters. The logical ERD in [`erd/README.md`](erd/README.md) is conceptual and does not claim that all entities already have durable tables. + +## 12. External protocol adapters + +### WebDriver BiDi + +**Planned.** WebDriver BiDi is an evolving W3C adapter contract. Its session/user-context/browsing-context identifiers are translated into OriginWeave-scoped internal identities. Protocol evolution is isolated behind versioned adapter tests. + +### Chrome DevTools Protocol + +**Planned.** The **Chrome DevTools Protocol** supplies Chromium-specific observation, diagnostics and experimental capabilities. OriginWeave binds supported protocol versions and does not expose unrestricted Runtime evaluation as a normal agent action. + +### WebMCP + +**Planned / experimental external dependency.** **WebMCP** can provide typed page tools. Tool schemas and outputs remain untrusted page-originated data and cannot grant OriginWeave authority. + +### Model Context Protocol + +**Planned.** The **Model Context Protocol** adapter exposes a small stable OriginWeave tool surface to orchestrators. MCP providers do not receive direct Chromium credentials or bypass the Rust policy/runtime boundary. + +### OriginWeave Protocol + +**Planned.** A versioned internal Browser Agent Protocol/OriginWeave Protocol is the product contract. BiDi, CDP, WebMCP and MCP are adapters rather than the core data model. + +## 13. Manifest V3 extension requirements + +**Accepted architecture / Planned compatibility program.** OriginWeave preserves Chromium's extension implementation rather than rebuilding Chrome APIs in Rust. Agent authority remains separate from ordinary extension permissions. A future signed policy registry controls which extensions may observe or propose agent actions. + +Compatibility acceptance includes installation/update, extension service-worker lifecycle, content scripts, storage, scripting, DNR, native messaging, downloads, side panel, restart persistence and explicit task-mode isolation. + +## 14. Prompt-injection and model boundary + +### 14.1 Trust classes + +```text +trusted_instruction +untrusted_observation +protected_secret +``` + +No automatic transformation may promote an `untrusted_observation` into `trusted_instruction`. + +### 14.2 LLM authority + +The model may propose plans, classifications or typed actions but cannot: + +- create capabilities; +- expand origin/destination/route authority; +- reveal raw secrets; +- manufacture approval; +- change deterministic policy; +- make a failed post-condition successful; +- reinterpret missing required GitHub/release evidence as passing. + +### 14.3 Model-backed tests and automation + +Live model work uses GitHub Secret **`NVIDIA_NIM_API_KEY`** through a bounded trusted path and preferably `contextual-orchestrator` where appropriate. Scheduled autonomous development uses an immutably pinned OpenCode Agent. **`COPILOT_GITHUB_TOKEN`** is not a development-scheduler credential. Deterministic repository gates run before optional model credentials are materialized. + +## 15. Error, retry, timeout and cancellation requirements + +### 15.1 Typed errors + +Each boundary returns errors that preserve the responsible layer and safe underlying cause without leaking credentials or protected payloads. + +### 15.2 Retry + +Retry is allow-listed for evidence-classified transient failures. Deterministic validation, permission, origin/destination, identity, malformed-input and policy failures are not retried merely to consume an attempt budget. + +### 15.3 Timeouts + +Per-layer timeouts do not substitute for an end-to-end deadline. Future composed runtime work must carry an explicit task/deadline budget and allocate remaining time to adapters rather than independently resetting unlimited timers. + +### 15.4 Cancellation + +Long-running tasks and external model calls require cancellation semantics that preserve evidence of what was attempted, what may have committed externally, and what remains safe to retry. + +## 16. Concurrency requirements + +- Browser/session state is tenant/task scoped; no in-process global singleton may become authority. +- Node/action validation occurs immediately before execution to close stale-state races. +- Sensitive-handle use becomes atomic in the trusted broker. +- Migration/release/automation writer leases prevent competing repository writers. +- Platform compute pools avoid avoidable oversubscription between Chromium, Rust and model runtimes. + +## 17. Persistence and data naming + +OriginWeave-owned persistent database objects use descriptive names containing at least two semantic words and `snake_case` by default. Examples: + +```text +agent_session +browser_profile +page_snapshot +semantic_node +action_event +policy_decision +provenance_record +resource_budget +extension_grant +task_checkpoint +network_exchange +download_artifact +``` + +The conceptual model is defined in [`erd/README.md`](erd/README.md). Adapters may use WARC/object storage/relational stores independently; cross-service application database access is not an integration contract. + +## 18. Security and enterprise controls + +The implementation targets evidence useful for CSAP/SOC 2-oriented secure operation without claiming certification. Requirements include least privilege, tenant separation, encrypted sensitive persistence, key lifecycle, purpose limitation, retention/export control, auditable privileged access, incident/vulnerability management, immutable build provenance, dependency review, sandbox/site isolation preservation and explicit egress policy. + +Renderer compromise is within the threat model; privileged validation occurs outside renderer-controlled state. + +## 19. Accessibility requirements + +Product UI targets WCAG 2.2 AA / ISO/IEC 40500:2025-aligned evidence. Approval, evidence, policy, task and resource interfaces require keyboard operation, visible focus, accessible state/error announcements, non-color-only risk cues, safe confirmation flows and exact-value alternatives for diagrams/charts. + +## 20. Test strategy + +### Implemented kernels + +Require deterministic unit/property/integration tests for canonicalization, classification, rebinding, redirects, direct peers, TLS identity, policy, resources and evidence. + +### Browser vertical slice + +Requires real browser integration tests covering isolated contexts, stale nodes, iframes/shadow DOM where supported, origin changes, typed actions, post-conditions, crashes, cancellations and governed real network composition. + +### Security + +Cover hostile Unicode/URLs, prompt injection, hidden content, redirect/private-address attempts, DNS rebinding, metadata endpoints, proxy bypass, certificate confusion, request smuggling/framing, decompression/resource exhaustion, MIME/integrity confusion, secret replay and cross-tenant authority. + +### Resource + +Cover CPU/RAM/VRAM pressure and foreground-interaction fallback on declared hardware profiles. + +### Interoperability + +Maintain versioned adapter contracts for BiDi/CDP/MCP/WebMCP and a Manifest V3 compatibility farm. + +### Quality gate + +Owned production code must satisfy the repository's exact function/line/region/statement/branch coverage policy and public rustdoc/docstring contract. Tests must measure real behavior rather than exclude production paths. + +## 21. Observability and operability + +**Planned.** OpenTelemetry-compatible metrics/traces and durable audit should expose at least: + +- task/session state and failure class; +- policy/approval denials; +- stale node and post-condition failures; +- destination/route/TLS/HTTP timing and rejection categories; +- resource pressure and mitigation decisions; +- observation compression/cache size; +- provider/model invocation outcomes without raw secrets; +- provenance completeness; +- crash/cancel/recovery state. + +Operator workflows include cancellation, quarantine, bounded retry, evidence inspection, rollback, supported-version upgrade and incident reopening. + +## 22. Release requirements + +A release is valid only from an exact protected head whose required CI, security, exact owned-code coverage, packaging, SBOM/provenance, reproducibility, supported Chromium/protocol/extension compatibility, accessibility, migration/rollback, independent review and release-acceptance evidence are all satisfied. + +Feature-branch green status is not protected-main operational proof. Incident repairs that affect scheduled/runtime behavior require protected-main execution evidence after merge. + +## 23. Documentation change control + +A material change to any of the following must update the authoritative documentation graph in the same or prerequisite reviewed change: + +- product surface or execution mode; +- origin/destination/route/TCP/TLS/HTTP authority; +- session/context/document/node lifetime; +- risk/approval/sensitive-data/secret authority; +- evidence/provenance schema; +- observation hierarchy or action lifecycle; +- resource scheduling/telemetry contract; +- external protocol/version boundary; +- enterprise privacy/security/tenancy contract; +- release acceptance or rollback semantics. + +If a decision is not implemented, the documentation must retain `Planned`, `Proposed`, or `Open` status rather than silently describe it as shipped. diff --git a/docs/adr/0001-chromium-compatibility-kernel.md b/docs/adr/0001-chromium-compatibility-kernel.md index 0be577b49..91f55a6f4 100644 --- a/docs/adr/0001-chromium-compatibility-kernel.md +++ b/docs/adr/0001-chromium-compatibility-kernel.md @@ -2,19 +2,85 @@ - Status: Accepted - Date: 2026-08-05 +- Supersedes: none +- Superseded by: none ## Context -OriginWeave needs modern web compatibility, JavaScript execution, graphics acceleration, process isolation, and Manifest V3 extension compatibility. Reimplementing Blink, V8, the compositor, and extension runtime would consume the project while producing worse compatibility and slower security updates. +OriginWeave needs modern web compatibility, JavaScript execution, graphics acceleration, process isolation, extension compatibility, accessibility semantics, and security updates at browser cadence. Reimplementing Blink, V8, the compositor, networking integration, and the extension runtime as a browser-engine rewrite would consume the product while producing materially worse compatibility and slower vulnerability response. The product differentiation is the governed Rust control plane, agent/runtime policy, evidence, resource governance, and protocol surface rather than a new rendering engine. + +## Decision drivers + +- Chromium-compatible rendering and JavaScript behavior must remain credible for enterprise web applications. +- Security updates must be consumable on upstream browser cadence. +- OriginWeave-owned authority boundaries should be memory-safe where practical and independently testable. +- Experimental browser surfaces must not become the sole product authority. +- The architecture must permit stock-Chromium validation before a maintained Chromium distribution is justified. + +## Assumptions and authority boundaries + +Chromium is an untrusted-complexity compatibility kernel, not the policy authority. Rust-owned OriginWeave components govern session mode, capabilities, navigation authority, typed actions, secrets, resource budgets, and evidence. Browser-provided DOM, accessibility, network, WebMCP, CDP, or extension observations are inputs to those policies rather than instructions that can grant authority. + +## Options considered + +1. **Full browser-engine rewrite.** Rejected because compatibility, staffing, security maintenance, and time-to-market costs are disproportionate to product differentiation. +2. **Unmodified browser driven only by arbitrary automation scripts.** Rejected because it does not create durable typed authority boundaries and makes product semantics depend on unstable external automation behavior. +3. **Chromium compatibility kernel plus Rust control plane.** Selected because it preserves web compatibility while keeping OriginWeave policy and evidence semantics independently owned. ## Decision -Chromium remains the compatibility kernel. New OriginWeave product behavior is implemented in Rust control-plane modules connected through narrow, validated adapters. Chromium patches are limited to integration points that cannot be supplied through WebDriver BiDi, CDP, Mojo, or an external process boundary. +Chromium remains the compatibility kernel. New OriginWeave product behavior is implemented in Rust control-plane modules connected through narrow, validated, versioned adapters. Chromium patches are limited to integration points that cannot be supplied safely through WebDriver BiDi, stable or pinned CDP surfaces, Mojo, extension APIs, or an external process boundary. Any tip-of-tree or experimental browser interface remains behind an OriginWeave-owned adapter and cannot become the sole source of product authority. + +Chromium's sandbox, multi-process model, and Site Isolation remain security boundaries that OriginWeave preserves rather than replacing. OriginWeave nevertheless assumes renderer compromise is possible and keeps privileged policy/secret/evidence decisions outside renderer authority. Chromium's Rust support and supported C++/Rust interoperability mechanisms are implementation inputs, not permission to move unvalidated browser types directly across the control-plane boundary. ## Consequences -- OriginWeave inherits Chromium's large upstream surface and must track security releases. -- The project can validate product demand with a stock Chromium sidecar before maintaining a distribution. -- Chrome Manifest V3 compatibility remains achievable. -- Rust ownership and memory safety apply to new OriginWeave modules, not to every line of Chromium. -- Any proposal to replace Blink or V8 requires a superseding ADR with compatibility, security-update, staffing, and benchmark evidence. +- OriginWeave inherits Chromium's large upstream attack and maintenance surface and must track security releases. +- The project can validate product demand with stock Chromium before maintaining a downstream distribution. +- Manifest V3 and mainstream web compatibility remain achievable. +- Rust ownership and memory-safety guarantees apply to OriginWeave-owned control-plane modules, not every line of Chromium. +- Integration adapters become explicit compatibility contracts that require versioning and conformance tests. + +## Failure and degraded behavior + +If a Chromium upgrade breaks an adapter, OriginWeave must fail closed for the affected governed capability rather than bypass policy through arbitrary JavaScript or silently downgrade evidence. Read-only Human Mode may remain available when its own safety contract is unaffected. A browser-version rollback is acceptable only to a still-supported, security-reviewed artifact and must preserve evidence of the downgrade. + +## Security / privacy / governance impact + +Chromium compromise is modeled as a renderer/kernel threat and must not grant policy, secret-broker, tenant, or approval authority. Secrets are delivered through opaque handles and trusted broker paths rather than model-visible or page-visible raw values. Browser observations are untrusted data. Enterprise logging must distinguish browser evidence from OriginWeave policy decisions. + +## Tests and acceptance evidence + +Acceptance requires compatibility smoke tests against supported Chromium versions, adapter conformance tests, hostile renderer/input tests, session-isolation tests, security update rehearsal, and exact evidence that a broken/unsupported adapter fails closed. A proposal to replace Blink or V8 requires measured compatibility, security-update, staffing, migration, and benchmark evidence rather than architectural preference. + +## Migration and rollback + +Adapters are versioned so a Chromium update can be canaried and rolled back independently of OriginWeave protocol consumers. Rollback must pin an immutable known-good browser artifact, preserve the same Rust policy boundary, and record the artifact/version in provenance. No rollback may re-enable a deprecated arbitrary-script authority path. + +## Open follow-ups + +- Define the supported Chromium version window and update SLO. +- Complete conformance matrices for BiDi/CDP/WebMCP/extension adapters. +- Decide when commercial demand justifies maintaining a signed OriginWeave Chromium distribution. + +## Supersession / reversal conditions + +Supersede this ADR only if another engine or an OriginWeave-owned engine demonstrates equivalent target-web compatibility, materially better security/update economics, sustainable staffing, migration tooling, and buyer-visible benefit. A narrow embedded-engine experiment does not by itself reverse this decision. + +## References + +Chromium. (n.d.-a). *Getting started with Rust in Chromium*. Chromium source documentation. Retrieved August 9, 2026, from https://chromium.googlesource.com/chromium/src/+/refs/heads/main/docs/rust/README.md + +Chromium. (n.d.-b). *Process model and Site Isolation*. Chromium source documentation. Retrieved August 9, 2026, from https://chromium.googlesource.com/chromium/src.git/+/refs/heads/main/docs/process_model_and_site_isolation.md + +Chromium. (n.d.-c). *Sandbox*. Chromium source documentation. Retrieved August 9, 2026, from https://chromium.googlesource.com/chromium/src/+/main/docs/design/sandbox.md + +Chromium. (n.d.-d). *Threat model and defenses against compromised renderers*. Chromium source documentation. Retrieved August 9, 2026, from https://chromium.googlesource.com/chromium/src.git/+/main/docs/security/compromised-renderers.md + +Chrome DevTools Protocol. (2026). *Chrome DevTools Protocol — latest (tip-of-tree)*. Chromium. Retrieved August 9, 2026, from https://chromedevtools.github.io/devtools-protocol/tot/ + +World Wide Web Consortium. (2026, June 29). *WebDriver BiDi* [Working Draft]. https://www.w3.org/TR/2026/WD-webdriver-bidi-20260629/ + +## Related documents + +See `docs/doctoring.md`, `docs/doctoring/product-documentation-baseline.md`, and ADR 0100 for current Rust/protocol evidence. diff --git a/docs/adr/0100-rust-control-plane-boundary.md b/docs/adr/0100-rust-control-plane-boundary.md new file mode 100644 index 000000000..cb1b55183 --- /dev/null +++ b/docs/adr/0100-rust-control-plane-boundary.md @@ -0,0 +1,74 @@ +# ADR 0100: Rust control-plane boundary + +- Status: Proposed +- Date: 2026-08-09 +- Supersedes: none +- Superseded by: none + +## Context + +OriginWeave is intended to be a Chromium-compatible enterprise agentic web runtime, not a thin automation script collection. The Chromium compatibility kernel owns rendering and browser mechanics; OriginWeave must own the authority-bearing semantics that buyers rely on: execution mode, capabilities, origin and destination policy, typed actions, approvals, secret brokering, resource governance, provenance, and the versioned OriginWeave Protocol. Letting browser scripts or experimental DevTools domains become the policy authority would make those semantics unstable and difficult to audit. + +## Decision drivers + +- Memory-safe ownership for new authority-bearing product code. +- Stable semantics across Chromium and adapter upgrades. +- Deterministic, testable policy before side effects. +- Clear separation between browser evidence and product authority. +- A module model that can operate independently or as part of a larger enterprise control plane. + +## Assumptions and authority boundaries + +The Chromium compatibility kernel may be compromised or return malformed observations. Rust control-plane components are trusted only to the extent established by their own tests, provenance, and runtime isolation. Browser-originated DOM, accessibility, network, CDP, WebMCP, and visual data are evidence inputs. They do not grant capabilities or approvals. + +## Options considered + +1. Browser-extension or JavaScript-first control plane: rejected because arbitrary page-adjacent code is too close to untrusted content and unstable browser APIs. +2. Chromium-fork-only implementation: rejected because authority semantics would become tightly coupled to a large C++ codebase and downstream patch maintenance. +3. Rust control plane around Chromium compatibility kernel: selected. + +## Decision + +OriginWeave-owned authority-bearing behavior is implemented in a Rust control plane with narrow adapters to Chromium and external protocols. Adapters translate evidence and commands but cannot silently widen capability, origin, approval, secret, resource, or provenance authority. Arbitrary JavaScript is not a control-plane escape hatch. Experimental interfaces remain replaceable adapters behind versioned internal contracts. + +The boundary uses data-oriented versioned messages and narrow FFI/IPC surfaces rather than sharing browser-owned mutable objects across trust boundaries. Rust type safety, ownership, and `Send`/`Sync` discipline are useful implementation controls but do not themselves validate untrusted IPC or browser data. Chromium/Rust integration follows supported Chromium mechanisms such as `cxx`/Crubit or Mojo where appropriate, with explicit validation at the OriginWeave boundary. + +## Consequences + +The Rust crates become the durable product boundary and must maintain strict APIs, rustdoc, compatibility tests, and exact owned-code coverage. Some browser operations require additional adapter work instead of direct scripting. Chromium integration can evolve without redefining policy semantics. + +## Failure and degraded behavior + +If a required adapter is unavailable or incompatible, the governed capability fails closed. Human browsing may degrade independently where safe. The runtime must not switch to an ungoverned script path, discard provenance, or weaken approval requirements merely to preserve feature availability. + +## Security / privacy / governance impact + +Secret material, approval authority, tenant policy, and high-risk action decisions remain outside renderer/page authority. Rust boundaries reduce accidental memory-unsafety in OriginWeave-owned code but do not imply Chromium itself is memory-safe or that unsafe FFI is automatically trustworthy. Evidence must identify which component made each decision. + +## Tests and acceptance evidence + +Require crate-level API and property tests, adapter conformance tests, hostile-input tests, renderer-compromise simulations, serialization/version tests, FFI/IPC boundary tests, exact 100% owned production coverage, rustdoc, Clippy, and end-to-end tests proving that adapter failure cannot bypass policy. Architecture documentation must map each authority to an owning module. + +## Migration and rollback + +Migrate browser-facing functionality behind Rust adapter traits before deprecating legacy paths. Rollback may restore a previous compatible adapter version, but cannot restore an arbitrary-script authority path or cross the secret/policy boundary. + +## Open follow-ups + +Define the stable internal adapter protocol and compatibility matrix; identify the minimum Chromium integration points that require downstream patches rather than external APIs. + +## Supersession / reversal conditions + +Supersede only if another implementation boundary demonstrates equal or better memory safety, auditability, browser compatibility, migration economics, and fail-closed authority semantics with production evidence. + +## References + +Chromium. (n.d.-a). *Getting started with Rust in Chromium*. Chromium source documentation. Retrieved August 9, 2026, from https://chromium.googlesource.com/chromium/src/+/refs/heads/main/docs/rust/README.md + +Chromium. (n.d.-b). *Crubit C++/Rust interoperability*. Chromium source documentation. Retrieved August 9, 2026, from https://chromium.googlesource.com/chromium/src/+/refs/heads/main/docs/rust/crubit.md + +The Rust Project Developers. (n.d.). *Send and Sync*. The Rustonomicon. Retrieved August 9, 2026, from https://doc.rust-lang.org/nomicon/send-and-sync.html + +## Related documents + +See ADR 0001, `ARCHITECTURE.md`, `docs/TRD.md`, and `docs/doctoring/product-documentation-baseline.md`. diff --git a/docs/adr/0101-isolated-execution-profile-modes.md b/docs/adr/0101-isolated-execution-profile-modes.md new file mode 100644 index 000000000..20117e86d --- /dev/null +++ b/docs/adr/0101-isolated-execution-profile-modes.md @@ -0,0 +1,74 @@ +# ADR 0101: Isolated execution and profile modes + +- Status: Proposed +- Date: 2026-08-09 +- Supersedes: none +- Superseded by: none + +## Context + +OriginWeave serves materially different authority models: a person browsing directly, an assistant helping while a person remains in control, a delegated agent task, and a crawler collecting public material. Treating these modes as cosmetic labels would allow cookies, approvals, secrets, navigation history, or write capabilities to cross trust boundaries. Enterprise buyers also need predictable isolation between users, tasks, tenants, and automated collection jobs. + +## Decision drivers + +- Human, Assist, Agent Task, and Crawler modes have different mutability and approval semantics. +- Browser profile state must not become an implicit capability grant. +- Delegated tasks require bounded lifetime, cancellation, and provenance. +- Crawler execution must stay read-only and policy/rate/robots aware. +- Enterprise deployments require tenant and user isolation that can be audited. + +## Assumptions and authority boundaries + +A browser profile stores potentially sensitive state but does not itself authorize an action. Session mode, declared purpose, capabilities, origins, approval evidence, and secret handles are explicit control-plane inputs. Page content cannot switch mode or enlarge authority. Chromium renderer/process isolation reduces blast radius but is not a substitute for OriginWeave tenant/task/profile isolation or control-plane authorization. + +## Options considered + +1. One shared profile and runtime with mode flags: rejected because state leakage and confused-deputy risk are too high. +2. Separate applications for every mode: rejected because it duplicates the compatibility/runtime stack and weakens cross-mode consistency. +3. One product with isolated profiles/contexts and explicit mode policy: selected. + +## Decision + +OriginWeave defines four governed execution modes: Human, Assist, Agent Task, and Crawler. Each session binds an explicit mode, purpose, tenant/user/task identity where applicable, isolated browser profile or context policy, capability set, origin grants, resource budget, and evidence stream. Agent Task and Crawler executions use isolated task contexts by default. Crawler mode is read-only. Assist mode may prepare reversible work but state-changing actions remain governed. Human Mode does not silently transfer direct browser control to an autonomous agent. + +Browser-context primitives supplied by Chromium/CDP are adapters for isolation, not OriginWeave's semantic authority. Context creation, disposal, storage/cookie partitioning, download ownership, permissions, cache/history behavior, and crash recovery must be bound to the OriginWeave session/task lifecycle and tested for supported browser versions. Reusing a context or profile across tasks requires an explicit reviewed policy and must never transfer prior task approvals, secret handles, or write capabilities. + +## Consequences + +Product APIs must carry mode and session identity. Profile reuse requires an explicit policy rather than convenience. More isolation increases browser-process and storage overhead, so the resource governor must account for it. Evidence can reliably attribute actions to the correct mode and task. + +## Failure and degraded behavior + +If profile isolation cannot be established, automated modes fail closed before loading sensitive state. A task cancellation revokes task-scoped authority and stops further state-changing actions. Recovery may reopen a fresh isolated context from a checkpoint only when the checkpoint does not smuggle stale secret, approval, or document authority. + +## Security / privacy / governance impact + +Cross-tenant, cross-user, and cross-task cookie/storage leakage is a high-severity boundary violation. Secret handles and approval evidence are scoped independently of browser storage. Retention and export policies apply to profile data and provenance separately. Crawler identity and purpose must remain distinguishable from a human session. + +## Tests and acceptance evidence + +Require cross-mode isolation tests, cookie/storage partition tests, task cancellation tests, tenant separation tests, profile/context create-dispose tests, download/cache/history isolation tests, profile lifecycle/crash-recovery tests, crawler write-denial tests, and evidence assertions proving mode/purpose/session identity on actions. Hostile page content must be unable to switch execution mode. Supported Chromium versions must prove that browser-context disposal makes the task context unavailable before task-scoped authority is considered revoked successfully. + +## Migration and rollback + +Introduce explicit session-mode/profile identifiers before deprecating any shared-state automation path. Rollback can disable an automated mode but must not collapse isolated contexts into one shared profile. + +## Open follow-ups + +Define enterprise profile-retention defaults, tenant keying, SSO/SCIM bindings, and checkpoint portability across compatible browser versions. + +## Supersession / reversal conditions + +Supersede only when an alternative isolation model proves equivalent cross-user/task/tenant containment, lower operational cost, and equally auditable authority semantics under hostile-state tests. + +## References + +Chrome DevTools Protocol. (2026). *Target domain*. Chromium. Retrieved August 9, 2026, from https://chromedevtools.github.io/devtools-protocol/tot/Target/ + +Chromium. (n.d.-a). *Process model and Site Isolation*. Chromium source documentation. Retrieved August 9, 2026, from https://chromium.googlesource.com/chromium/src.git/+/refs/heads/main/docs/process_model_and_site_isolation.md + +Chromium. (n.d.-b). *Threat model and defenses against compromised renderers*. Chromium source documentation. Retrieved August 9, 2026, from https://chromium.googlesource.com/chromium/src.git/+/main/docs/security/compromised-renderers.md + +## Related documents + +See `docs/PRD.md`, `docs/TRD.md`, `docs/THREAT_MODEL.md`, and the conceptual entities in `docs/erd/README.md`. diff --git a/docs/adr/0102-typed-actions-and-arbitrary-js.md b/docs/adr/0102-typed-actions-and-arbitrary-js.md new file mode 100644 index 000000000..438be43bb --- /dev/null +++ b/docs/adr/0102-typed-actions-and-arbitrary-js.md @@ -0,0 +1,72 @@ +# ADR 0102: Typed actions instead of arbitrary JavaScript authority + +- Status: Proposed +- Date: 2026-08-09 +- Supersedes: none +- Superseded by: none + +## Context + +A browser agent can express nearly any behavior by evaluating arbitrary JavaScript, but that flexibility destroys the product's ability to reason about capability, risk, target origin, secret use, approval, resource cost, and provenance before execution. OriginWeave needs auditable action semantics that remain stable even when page content is adversarial and browser adapters change. + +## Decision drivers + +- State-changing behavior must be classifiable before execution. +- Policy must reason about exact capability, target, intent, and approval scope. +- Evidence should describe meaningful business actions rather than opaque script blobs. +- Web content is untrusted data and cannot become instruction authority. +- Compatibility escape hatches must not become routine privileged paths. + +## Assumptions and authority boundaries + +The policy engine receives typed requests from trusted control-plane code. Page-derived selectors, values, and observations remain untrusted parameters until validated. Browser adapters may translate a typed action into lower-level protocol calls, but the adapter cannot grant a new action kind or expand its declared authority. WebDriver BiDi and CDP provide browser operations; they do not define OriginWeave's business-risk, approval, tenant, or secret authority. + +## Options considered + +1. Permit arbitrary JavaScript for all automation: rejected because risk and provenance become opaque. +2. Maintain a deny-list of dangerous script operations: rejected because JavaScript is too expressive for a complete negative policy. +3. Expose typed actions with an exceptional, separately governed diagnostic script facility: selected. + +## Decision + +Product automation uses a versioned typed action API for observation, extraction, navigation, download, drafting, submission, upload, brokered secret fill, purchase, deletion, permission management, and future explicitly modeled actions. Arbitrary JavaScript is not an implicit fallback for failed typed actions. If a diagnostic or compatibility script facility is introduced, it is disabled for ordinary autonomous execution, separately capability-gated, origin-scoped, evidence-recorded, and prohibited from bypassing secret, approval, network, or tenant policy. + +Adapters prefer browser mechanisms that preserve native user-facing semantics and post-condition observability. A low-level CDP `Runtime.evaluate` or BiDi script operation remains a protocol primitive, not permission for a planner/model to supply executable code. If a future typed action needs script-backed implementation internally, the script is product-owned, versioned, reviewed, parameterized through validated data, and bound to the same action/risk/post-condition contract. + +## Consequences + +New web behaviors sometimes require a new typed action or adapter capability instead of a one-line script. In return, risk classes, approvals, test coverage, compatibility, and evidence become deterministic. SDKs can provide stable contracts across browser backends. + +## Failure and degraded behavior + +When no typed action can express a requested effect, OriginWeave reports an unsupported capability or requires explicit human handling. It must not silently evaluate arbitrary JavaScript, inject a privileged extension script, or mark the task successful without post-condition evidence. + +## Security / privacy / governance impact + +Typed actions reduce prompt-injection and confused-deputy blast radius by constraining what model output can request. Secret delivery remains opaque-handle based. High-risk actions preserve governed approval, and evidence can record parameters after credential-safe redaction. Protocol script evaluation is treated as code execution within the browser context and remains outside ordinary autonomous model authority. + +## Tests and acceptance evidence + +Require a table-driven mapping from action kind to capability, mutability, risk, secret usage, and post-condition requirements; tests that web content cannot create trusted instructions; adapter tests proving no arbitrary-script fallback; hostile selector/value tests; tests that model/page strings cannot reach CDP/BiDi script-evaluation code paths as executable source; and end-to-end evidence that denied or unsupported actions cause no side effect. + +## Migration and rollback + +Migrate existing scripted flows action-by-action. During migration, legacy script paths remain explicitly marked experimental and cannot receive broader authority than the typed equivalent. Rollback may disable a newly introduced action but may not reactivate an unrestricted script fallback. + +## Open follow-ups + +Define extension/SDK APIs for registering future typed actions and determine whether a non-production diagnostic scripting surface is needed at all. + +## Supersession / reversal conditions + +Supersede only if a more expressive action representation preserves equivalent pre-execution risk classification, capability enforcement, secret isolation, approval semantics, provenance, and deterministic denial under adversarial tests. + +## References + +Chrome DevTools Protocol. (2026). *Runtime domain*. Chromium. Retrieved August 9, 2026, from https://chromedevtools.github.io/devtools-protocol/tot/Runtime/ + +World Wide Web Consortium. (2026, June 29). *WebDriver BiDi* [Working Draft]. https://www.w3.org/TR/2026/WD-webdriver-bidi-20260629/ + +## Related documents + +See ADR 0002, `crates/originweave-core`, `crates/originweave-policy`, `docs/API_CONTRACT.md`, and `docs/THREAT_MODEL.md`. diff --git a/docs/adr/0103-semantic-observation-and-stale-node-identity.md b/docs/adr/0103-semantic-observation-and-stale-node-identity.md new file mode 100644 index 000000000..389e98922 --- /dev/null +++ b/docs/adr/0103-semantic-observation-and-stale-node-identity.md @@ -0,0 +1,95 @@ +# ADR 0103: Semantic observation precedence and stale-node identity + +- Status: Proposed +- Date: 2026-08-09 +- Supersedes: none +- Superseded by: none + +## Context + +Agentic browsing needs compact, stable observations without treating one browser representation as universally authoritative. WebMCP or structured application data can expose high-level semantics, accessibility trees can expose user-visible structure, DOM/layout can fill gaps, and visual interpretation is sometimes necessary. Each layer can be incomplete, adversarial, stale, or unavailable. Node references are particularly dangerous after navigation or document mutation because a selector or backend identifier can refer to different state later. + +## Decision drivers + +- Prefer the highest-signal structured representation while retaining independent verification. +- Avoid blind trust in experimental WebMCP or page-authored semantics. +- Preserve accessibility and user-visible meaning. +- Prevent actions against stale nodes after document replacement or relevant mutation. +- Keep observation provenance sufficient to explain what the agent saw. + +## Assumptions and authority boundaries + +All page-derived observations are untrusted data. Observation sources can inform planning but cannot grant action capability or approval. A semantic node identity is meaningful only within its browser session/context and document epoch. Network or structured-data observations may corroborate semantics but do not override policy. + +## Options considered + +1. DOM-only observation: rejected because it is noisy and can diverge from accessibility or application semantics. +2. Visual-only observation: rejected because it is expensive, difficult to make deterministic, and loses structured provenance. +3. WebMCP-first authority: rejected because WebMCP is experimental and page/tool output can contain prompt injection. +4. Ordered multi-source observation with explicit provenance and stale identity: selected. + +## Decision + +Observation precedence is WebMCP/explicit structured application contracts when available, then structured data and network-derived semantics, accessibility semantics, DOM, layout, and bounded visual fallback. Higher precedence means preferred representation, not unquestioned trust. Every observation records source and document identity. + +Actionable semantic nodes bind to the exact browser session, browsing context, and a monotonically increasing `document_epoch`. The browser adapter increments the epoch on cross-document navigation and on any same-document lifecycle event that can invalidate the meaning or target identity of an actionable observation, including replacement/removal of an observed DOM node, reassignment of the node's actionable role/name/state, relevant accessibility-tree invalidation, frame-document replacement, or a subtree mutation that replaces the observed target rather than merely changing unrelated descendants. The adapter may coalesce multiple mutation notifications into one epoch increment, but it must never retain the old epoch when an actionable handle's target identity or user-visible semantics could have changed. + +The adapter publishes an explicit observation-invalidation lifecycle event before a stale handle can be executed. Any action request carrying a semantic-node handle must revalidate session, browsing context, epoch, and node identity at the **action linearization point**: the trusted adapter boundary immediately adjacent to the browser side effect. Where the browser integration can provide an atomic compare-and-dispatch primitive, validation and dispatch use that primitive. Otherwise the adapter performs the same session/context/origin/epoch/node check again immediately before the side effect and aborts with a stale-reference result if a **competing mutation** or invalidation event occurs between the earlier policy validation and dispatch. The adapter must never rely on a pre-dispatch check whose result can become stale before input delivery. + +If the current epoch differs, or the adapter cannot prove the node identity still denotes the same current actionable target at the linearization point, the request fails without producing the side effect and must be re-observed. **Re-observation** produces a new handle bound to the new epoch; matching accessible text or selectors alone does not revive the old handle. + +Purely non-semantic mutations may avoid an epoch increment only when the adapter has deterministic evidence that they cannot affect any emitted actionable handle. That optimization is adapter-specific and requires conformance tests; uncertainty invalidates rather than preserves the handle. + +## Consequences + +The control plane needs normalization and conflict handling across observation sources. Visual fallback remains bounded rather than becoming the default. Agents gain smaller, more meaningful snapshots while policy and verification remain independent. Browser adapters must expose navigation, DOM, and accessibility lifecycle evidence reliably enough to invalidate stale references, and coarse invalidation is preferred over unsafe handle reuse. The action adapter also owns a small synchronization/linearization responsibility so a valid policy decision cannot authorize a stale target after the page changes. + +## Failure and degraded behavior + +If a preferred source is absent, malformed, oversized, contradictory, or unsupported, OriginWeave falls back to the next governed source and records degradation. If document identity or mutation freshness cannot be established, node-targeted state changes fail closed. A stale node must produce a deterministic stale-reference result, never an automatic best-effort action against a newly matched element. If the adapter cannot establish a safe action linearization point, the action is unsupported rather than executed with a race window. + +## Security / privacy / governance impact + +Prompt injection in WebMCP, DOM, accessibility names, structured data, or visual text never becomes instruction authority. Sensitive observation content follows privacy, retention, and selective-disclosure policy. Provenance records which source contributed each semantic claim so enterprise audit can distinguish browser evidence from agent inference. Same-document invalidation and side-effect-adjacent revalidation prevent a hostile or rapidly mutating page from replacing a reviewed target between observation, policy validation, and action while preserving an apparently similar node reference. + +## Tests and acceptance evidence + +Require cross-source conflict tests, hostile WebMCP/DOM/accessibility payload tests, navigation/document-replacement stale-node tests, and same-document mutation tests that prove: + +- a handle emitted at epoch N is rejected after the observed target is removed/replaced; +- a handle emitted at epoch N is rejected after a relevant role/name/actionability accessibility mutation; +- unrelated mutations may preserve the epoch only under a tested adapter-specific non-semantic rule; +- re-observation after invalidation emits a handle at a later epoch and that current handle can succeed when all other policy gates pass; +- stale-handle rejection occurs before the trusted action adapter produces a side effect; +- a deterministic race fixture mutates the relevant DOM/accessibility target after initial authorization but before dispatch, and the stale handle is rejected at the action linearization point with no side effect; +- after that competing mutation, re-observation yields a current handle that succeeds only after all normal authority checks pass. + +Also require visual-fallback budget tests, accessibility preservation tests, browser-version adapter conformance tests, and end-to-end verification that stale references cause no side effect. + +## Migration and rollback + +Introduce source/provenance metadata, explicit invalidation events, document epoch, and the action-linearization revalidation contract before exposing durable semantic-node handles. Rollback may disable a higher-level adapter such as WebMCP and fall back to lower layers; it must not disable stale-node invalidation, side-effect-adjacent revalidation, or source provenance. + +## Open follow-ups + +Specify stable semantic-node serialization, mutation invalidation granularity per browser adapter, observation conflict scoring, browser-specific atomic compare-and-dispatch mechanisms, and supported-browser conformance matrices. + +## Supersession / reversal conditions + +Supersede if a standardized browser semantic interface achieves broad stable support and can provide equivalent provenance, injection resistance, accessibility fidelity, and race-safe stale-reference guarantees under production tests. + +## References + +Chrome DevTools Protocol. (2026). *Accessibility domain*. Chromium. Retrieved August 9, 2026, from https://chromedevtools.github.io/devtools-protocol/tot/Accessibility/ + +Chrome DevTools Protocol. (2026). *DOM domain*. Chromium. Retrieved August 9, 2026, from https://chromedevtools.github.io/devtools-protocol/tot/DOM/ + +Chrome DevTools Protocol. (2026). *DOMSnapshot domain*. Chromium. Retrieved August 9, 2026, from https://chromedevtools.github.io/devtools-protocol/tot/DOMSnapshot/ + +Chrome DevTools Protocol. (2026). *WebMCP domain*. Chromium. Retrieved August 9, 2026, from https://chromedevtools.github.io/devtools-protocol/tot/WebMCP/ + +World Wide Web Consortium. (2026, June 29). *WebDriver BiDi* [Working Draft]. https://www.w3.org/TR/2026/WD-webdriver-bidi-20260629/ + +## Related documents + +See `docs/TRD.md`, `docs/API_CONTRACT.md`, `docs/THREAT_MODEL.md`, `docs/uml/README.md`, and the session/document work tracked by the existing OriginWeave architecture. diff --git a/docs/adr/0104-prompt-injection-and-secret-authority.md b/docs/adr/0104-prompt-injection-and-secret-authority.md new file mode 100644 index 000000000..28da02a52 --- /dev/null +++ b/docs/adr/0104-prompt-injection-and-secret-authority.md @@ -0,0 +1,72 @@ +# ADR 0104: Prompt-injection and secret authority separation + +- Status: Proposed +- Date: 2026-08-09 +- Supersedes: none +- Superseded by: none + +## Context + +OriginWeave intentionally processes hostile web content while also supporting authenticated enterprise tasks. A page can contain text, WebMCP output, accessibility labels, structured data, downloads, or model-visible artifacts designed to impersonate instructions and solicit credentials. If the same channel can both describe page state and grant access to secrets or actions, prompt injection becomes an authority escalation rather than merely bad content. + +## Decision drivers + +- Raw webpage content is untrusted data, never instruction authority. +- Models must never receive raw secret values merely because a task needs authentication. +- Secret disclosure must be purpose-bound, origin-bound, action-bound, and auditable. +- High-risk side effects require policy and approval independent of model persuasion. +- Renderer compromise must not become secret-broker compromise. + +## Assumptions and authority boundaries + +Trusted instruction sources are explicit user or managed enterprise policy inputs accepted by the control plane. Page content, WebMCP/tool output, DOM, accessibility, network bodies, downloads, and model-generated interpretations are untrusted observations. The secret broker is a separate trusted component. The model receives an opaque handle or capability reference and never receives the underlying raw secret value. A website-specific exceptional flow must be represented as an independently reviewed typed broker operation that delivers only the required value through the trusted broker-to-browser integration path; it does not create a model-disclosure exception. + +## Options considered + +1. Put credentials in model context and rely on prompt hygiene: rejected because prompt injection can exfiltrate them. +2. Allow page scripts to request a password-manager API directly: rejected because the page would become the requester and policy authority. +3. Opaque secret handles resolved by a trusted broker only after independent policy authorization: selected. + +## Decision + +OriginWeave separates instruction, observation, policy, approval, and secret authority. A secret-fill or other explicitly typed broker action carries an opaque handle plus canonical target/action intent. Policy verifies mode, purpose, capability, origin, risk, approval, and secret-delivery mode before the trusted broker resolves anything. The broker binds resolution to the authorized session/task, destination/origin, purpose, field/action contract, expiry, and use policy and sends the minimum required value directly to the trusted browser integration path. The value does not pass through the model, page observation channel, planner, or generic tool result. Model-visible logs, evidence, errors, and provenance store opaque identifiers or redacted fingerprints, never raw secret material. + +## Consequences + +Authenticated automation requires explicit broker integration and cannot be implemented as arbitrary text substitution. Troubleshooting needs credential-safe evidence. Enterprise deployments can rotate or revoke secrets independently of task prompts. Websites with unconventional credential flows require new typed broker operations instead of model access to raw values. + +## Failure and degraded behavior + +If the broker is unavailable, authorization is stale, destination identity changes, or the handle cannot be resolved within scope, secret use fails closed. The runtime does not ask the model to reconstruct the credential, log the raw value, widen the destination, or fall back to model-visible disclosure. A task may continue only on paths that no longer require that secret and remain independently authorized. + +## Security / privacy / governance impact + +This is a primary prompt-injection containment boundary. Secret access is least-privilege, purpose-bound, selectively disclosed, and auditable. Tenant and user ownership are checked outside browser content. Evidence must prove the authorization decision and delivery event without containing the secret. Revocation and retention policies apply to handles and audit records separately from the secret store. + +## Tests and acceptance evidence + +Require hostile prompt-injection tests across DOM, WebMCP, accessibility, structured data, downloads, and network content; broker-origin mismatch tests; stale/revoked/over-used handle tests; renderer-compromise tests; log/evidence/model-context secret-leak scans; exact-action and task/session scope tests; typed exceptional broker-operation tests; and end-to-end proof that denied secret resolution causes no browser or model disclosure. + +## Migration and rollback + +Move any direct credential passing behind opaque broker handles before enabling model-backed authenticated tasks. Rollback may disable broker-backed automation and return control to a person; it must not restore model-visible raw-secret delivery. + +## Open follow-ups + +Finalize task/session-bound handle expiry, one-time or bounded-use semantics, atomic reservation, enterprise vault adapters, tenant keying, and recovery behavior for interrupted secret fills. + +## Supersession / reversal conditions + +Supersede only if an alternative proves equivalent isolation from untrusted content and model context, purpose/origin/action binding, revocation, least disclosure, and credential-free evidence under adversarial testing. Model-visible raw-secret delivery is not an acceptable supersession path. + +## References + +Chrome DevTools Protocol. (2026). *WebMCP domain*. Chromium. Retrieved August 9, 2026, from https://chromedevtools.github.io/devtools-protocol/tot/WebMCP/ + +National Institute of Standards and Technology. (2024). *Artificial intelligence risk management framework: Generative artificial intelligence profile* (NIST AI 600-1). https://doi.org/10.6028/NIST.AI.600-1 + +Rose, S., Borchert, O., Mitchell, S., & Connelly, S. (2020). *Zero trust architecture* (NIST Special Publication 800-207). National Institute of Standards and Technology. https://doi.org/10.6028/NIST.SP.800-207 + +## Related documents + +See ADR 0002, `SECURITY.md`, `docs/THREAT_MODEL.md`, `docs/API_CONTRACT.md`, `docs/DATA_GOVERNANCE.md`, and the sensitive-data work tracked in OriginWeave. diff --git a/docs/adr/0105-resource-governor-priority.md b/docs/adr/0105-resource-governor-priority.md new file mode 100644 index 000000000..8f3f4d2ca --- /dev/null +++ b/docs/adr/0105-resource-governor-priority.md @@ -0,0 +1,74 @@ +# ADR 0105: Resource governor and browser-over-model priority + +- Status: Proposed +- Date: 2026-08-09 +- Supersedes: none +- Superseded by: none + +## Context + +OriginWeave may run Chromium rendering, capture, local inference, remote-model orchestration, extraction, evidence processing, and multiple isolated sessions on the same host. CPU, RAM, GPU, VRAM, file descriptors, sockets, and disk are finite safety resources. A model or crawler that starves the browser can corrupt task semantics, crash tabs, lose evidence, or make a state-changing action unverifiable. Enterprise operation also requires predictable admission and degradation rather than best-effort overcommit. + +## Decision drivers + +- Preserve interactive/browser correctness before optional model throughput. +- Bound CPU, RAM, GPU, VRAM, network, storage, and concurrency per task/tenant. +- Make resource exhaustion an explicit policy/evidence event. +- Prefer deterministic degradation over host instability. +- Support capacity planning and SLOs. + +## Assumptions and authority boundaries + +The resource governor is a Rust control-plane authority. Browser and model runtimes report telemetry but cannot self-grant additional budget. A task's resource budget is separate from its action capabilities and cannot be enlarged by webpage content or model output. + +## Options considered + +1. Let the OS scheduler arbitrate all contention: rejected because it cannot express product priority or task budgets. +2. Give model inference priority to maximize agent throughput: rejected because browser starvation can invalidate observation/action correctness. +3. Explicit resource governor with browser correctness above optional model acceleration: selected. + +## Decision + +Every automated session receives an explicit resource budget and admission decision. The governor accounts for CPU capacity, RAM, GPU/VRAM, browser-process priority, model-process priority/residency, network concurrency, evidence/cache bytes, temporary/durable artifact pressure, file descriptors, and bounded queue/concurrency limits. Browser execution needed to preserve current task correctness and verifiable state has priority over optional local model acceleration. Under GPU/VRAM pressure the model degrades first: reduce concurrency or batch size, free model caches, use CPU or remote inference when policy permits, pause the model path, or fail it. Browser workloads are still bounded and may be rejected rather than overcommitted. + +A resource-budget version and mitigation decision are evidence-bearing control-plane values. Admission and mitigation evidence record quantities, units, resource owner/task, policy version, trigger, and applied mitigation without carrying page content. A `cpu_worker_limit` is a count of OriginWeave-controlled CPU compute workers/admitted execution slots, not a percentage of total host CPU and not authority to change Chromium's internal scheduler. + +## Consequences + +Throughput may be lower than unconstrained best effort, but failures become attributable and recoverable. Capacity planning can use explicit budgets. Local-model features need declared fallback semantics. Resource evidence becomes part of operability and buyer-visible reliability. + +## Failure and degraded behavior + +Admission failure occurs before launching work that cannot fit. Runtime pressure may suspend optional model work, reduce capture fidelity within documented bounds, or fail the task before a state-changing step. The governor must not kill evidence or browser processes in a way that falsely records task success. Recovery starts from an explicit checkpoint or fresh session after resources are available. + +## Security / privacy / governance impact + +Budgets mitigate resource-exhaustion attacks from hostile pages, crawls, model outputs, and tenants. Tenant quotas prevent noisy-neighbor denial of service. Telemetry must avoid leaking page or secret content and should record quantities, owners, policy versions, priorities, and decisions rather than sensitive payloads. + +## Tests and acceptance evidence + +Require deterministic admission tests; CPU-worker, RAM, GPU/VRAM, network-concurrency, evidence/storage-pressure, file-descriptor, and queue pressure tests; browser-vs-model process-priority tests; concurrent tenant/session tests; crash/restart tests; bounded queue tests; and evidence proving no state-changing action is marked verified when the browser needed for post-condition checking was evicted. GPU tests must prove model offload/pause occurs before protected foreground browser capacity is sacrificed under the configured policy. Performance tests must record workload, browser build, model/runtime, and hardware assumptions. + +## Migration and rollback + +Introduce accounting in observe-only mode before enforcing limits, then enable admission per resource class. Rollback may disable a new optimization or fallback but must retain hard safety bounds already required to prevent host instability and must not silently widen a previously enforced task budget. + +## Open follow-ups + +Define production default budgets, hardware classes, tenant quota APIs, remote-model fallback policy, supported telemetry adapters, and capacity/SLO dashboards. + +## Supersession / reversal conditions + +Supersede only if another scheduler demonstrates equivalent fail-closed resource isolation, tenant fairness, browser correctness, observability, and materially better utilization in representative workloads. + +## References + +Chromium. (n.d.). *MemoryInfra*. Chromium source documentation. Retrieved August 9, 2026, from https://chromium.googlesource.com/chromium/src/+/HEAD/docs/memory-infra/README.md + +Chromium. (n.d.). *Key concepts in Chrome memory*. Chromium source documentation. Retrieved August 9, 2026, from https://chromium.googlesource.com/chromium/src.git/+/HEAD/docs/memory/key_concepts.md + +V8 Project Authors. (2018, June 11). *Concurrent marking in V8*. https://v8.dev/blog/concurrent-marking + +## Related documents + +See `docs/OPERABILITY.md`, `docs/TEST_STRATEGY.md`, `docs/erd/README.md`, and the `originweave-resource` crate. diff --git a/docs/adr/0106-provenance-evidence-model.md b/docs/adr/0106-provenance-evidence-model.md new file mode 100644 index 000000000..0e2741f37 --- /dev/null +++ b/docs/adr/0106-provenance-evidence-model.md @@ -0,0 +1,74 @@ +# ADR 0106: Provenance-native evidence model + +- Status: Proposed +- Date: 2026-08-09 +- Supersedes: none +- Superseded by: none + +## Context + +OriginWeave must not merely act; it must let a user, operator, auditor, or downstream system establish what was observed, authorized, executed, and verified. Browser logs alone are not sufficient because they collapse observation, policy, action, network identity, approvals, and post-conditions. At the same time, evidence can itself contain sensitive or attacker-controlled content. The product needs a durable model compatible with web-archive and provenance concepts without claiming that every conceptual record is already persisted. + +## Decision drivers + +- `Browse. Act. Prove.` requires evidence as a first-class product output. +- Source observation, policy decision, action execution, and verification must remain distinct authorities. +- Evidence should support WARC-style capture and PROV-style derivation where useful. +- Credentials and unnecessary PII must not be copied into evidence. +- Crash recovery and export need stable identities and integrity metadata. + +## Assumptions and authority boundaries + +Evidence records describe events and artifacts; they do not retroactively authorize them. Browser/network payloads are untrusted content even when archived. Policy decisions and approval evidence are control-plane records. Raw secrets are outside the evidence model. Conceptual entities in the ERD are not automatically claims of database persistence. + +## Options considered + +1. Store only human-readable logs: rejected because provenance, machine verification, and linkage are weak. +2. Capture complete browser/network data indiscriminately: rejected because privacy, retention, and secret exposure become unacceptable. +3. Typed provenance graph with selective WARC/content records and explicit policy/action links: selected. + +## Decision + +OriginWeave maintains provenance-native evidence with stable identifiers for sessions, snapshots, network exchanges, content records, policy decisions, approvals, action events, artifacts, and verification outcomes. WARC-compatible records may preserve eligible web exchanges or content; PROV-style relations describe derivation and responsibility without making either external format the sole internal authority. Evidence binds logical origin, resolved destination, TCP peer, TLS identity, HTTP semantics, browser/session/document identity, action intent, policy outcome, approval reference, and post-condition where applicable. Sensitive values are omitted, redacted, tokenized, or represented by opaque handles/fingerprints according to policy. + +WARC and PROV are interoperability/export contracts, not substitutes for OriginWeave's internal authorization or evidence schema. A WARC record can contain untrusted or sensitive payload bytes and therefore inherits capture, retention, encryption, and export policy. A PROV entity/activity/agent relation records derivation or responsibility; it cannot manufacture authentication, authorization, durable completion, or tenant ownership not established by the producing system. + +## Consequences + +Capture becomes a designed product surface rather than incidental logging. Storage and retention need budgets. Consumers can distinguish a model claim from source evidence and an action request from verified completion. Export adapters can target WARC, provenance graphs, audit streams, or buyer-specific schemas. + +## Failure and degraded behavior + +If mandatory evidence cannot be recorded durably enough for a governed state-changing action, the action fails before execution or reports an explicit unverifiable failure; it is never marked proved. Read-only operations may degrade to reduced evidence only when the API contract declares that mode. Corrupt or incomplete evidence is quarantined rather than silently accepted. + +## Security / privacy / governance impact + +Evidence is tenant-scoped, selectively disclosed, encrypted as appropriate, retention-bounded, and auditable. Credential-bearing headers, cookies, secret values, and sensitive form data are excluded or transformed according to explicit schema policy. Integrity metadata and immutable artifact identities support tamper detection without claiming external certification. `docs/DATA_GOVERNANCE.md` defines the disclosure/retention boundary for protected content and derived artifacts. + +## Tests and acceptance evidence + +Require provenance-link tests, credential-leak tests, integrity/corruption tests, crash-recovery tests, WARC/export conformance where implemented, PROV relation/schema tests where implemented, retention/deletion tests, tenant-isolation tests, and end-to-end checks that state-changing actions link request, policy, approval, execution, and post-condition as separate records. Export tests must prove that disabled or unauthorized source bodies never appear merely because metadata provenance is exportable. + +## Migration and rollback + +Introduce stable evidence identifiers and schema versions before changing export formats. Migrations preserve old evidence semantics or explicitly mark unavailable fields. Rollback may revert an exporter but cannot collapse mandatory action and policy evidence into opaque logs. + +## Open follow-ups + +Finalize canonical evidence schemas, content-retention defaults, signing/attestation strategy, cross-system export identifiers, and buyer-controlled disclosure policies. + +## Supersession / reversal conditions + +Supersede only if a different evidence model provides equal or better derivation, integrity, privacy, interoperability, crash recovery, and machine-verifiable separation of observation, policy, action, and verification. + +## References + +International Organization for Standardization. (2017). *Information and documentation—WARC file format* (ISO 28500:2017). https://www.iso.org/standard/68004.html + +Lebo, T., Sahoo, S., & McGuinness, D. (Eds.). (2013). *PROV-O: The PROV ontology* (W3C Recommendation). World Wide Web Consortium. https://www.w3.org/TR/prov-o/ + +Moreau, L., & Missier, P. (Eds.). (2013). *PROV-DM: The PROV data model* (W3C Recommendation). World Wide Web Consortium. https://www.w3.org/TR/prov-dm/ + +## Related documents + +See ADR 0003, `docs/erd/README.md`, `docs/API_CONTRACT.md`, `docs/OPERABILITY.md`, and `docs/DATA_GOVERNANCE.md`. diff --git a/docs/adr/0107-browser-protocol-adapter-strategy.md b/docs/adr/0107-browser-protocol-adapter-strategy.md new file mode 100644 index 000000000..8923616be --- /dev/null +++ b/docs/adr/0107-browser-protocol-adapter-strategy.md @@ -0,0 +1,77 @@ +# ADR 0107: Versioned browser and agent protocol adapters + +- Status: Proposed +- Date: 2026-08-09 +- Supersedes: none +- Superseded by: none + +## Context + +OriginWeave must interoperate with Chromium and external automation/agent ecosystems without allowing any one unstable protocol to define the product. WebDriver BiDi is standards-track but evolving, Chrome DevTools Protocol includes tip-of-tree surfaces without backwards-compatibility guarantees, WebMCP is experimental, and Model Context Protocol is an external tool/context protocol rather than browser authority. Directly exposing these surfaces as the OriginWeave API would couple customers to provider churn and blur policy boundaries. + +## Decision drivers + +- Stable OriginWeave semantics across browser/provider upgrades. +- Standards-first interoperability where mature enough. +- Ability to use Chromium-specific capabilities without making experimental CDP the sole authority. +- Explicit trust boundaries for WebMCP and MCP content/tools. +- Conformance and compatibility testing per adapter version. + +## Assumptions and authority boundaries + +The OriginWeave Protocol and Rust control plane own product semantics. WebDriver BiDi, Chrome DevTools Protocol, WebMCP, and Model Context Protocol are adapters or evidence/tool transports. Adapter messages are validated and cannot directly grant capabilities, approvals, secrets, origin authority, or evidence truth. + +## Options considered + +1. CDP as the public product API: rejected because Chromium-specific and unstable tip-of-tree surfaces create vendor/version lock-in. +2. WebDriver BiDi only: rejected because not every required Chromium/experimental capability is standardized yet. +3. Expose all upstream protocols directly: rejected because clients would inherit incompatible authority models. +4. Versioned internal protocol with explicit BiDi/CDP/WebMCP/MCP adapters: selected. + +## Decision + +OriginWeave exposes its own versioned protocol for session, observation, query, typed action, policy/evidence, secret-handle, resource, and lifecycle semantics. Browser and ecosystem adapters map that protocol to supported WebDriver BiDi, stable or pinned CDP, WebMCP, and MCP surfaces. Prefer standards-track BiDi when it satisfies the contract. Use Chromium-specific CDP only behind versioned adapter capability declarations. Treat WebMCP outputs as untrusted page/tool observations. Treat MCP as an external integration boundary, not a source of OriginWeave authority. Experimental/tip-of-tree surfaces are optional and must have fallback or explicit unsupported behavior. + +MCP version negotiation is independent of the OriginWeave Protocol version. As of this review, MCP `2026-07-28` is the current released protocol generation; a future MCP change does not silently alter OriginWeave task, approval, secret, tenant, or browser semantics. MCP tool/resource content remains untrusted input and any server-to-client/user interaction capability is mediated by the same OriginWeave policy/approval boundaries as other adapter traffic. + +## Consequences + +OriginWeave carries adapter maintenance and version negotiation but gains a durable customer API. Multiple browser/control transports can coexist. New upstream capabilities do not silently change risk or action semantics. Compatibility matrices become release artifacts. + +## Failure and degraded behavior + +Adapter negotiation failure disables only affected capabilities. Unsupported or schema-incompatible messages fail closed with typed errors. OriginWeave must not bypass a failed adapter by exposing raw CDP or arbitrary JavaScript to an autonomous model. A standards adapter may fall back to a pinned vendor adapter only when the same OriginWeave semantic and security contract is proven. + +## Security / privacy / governance impact + +Protocol validation occurs before messages influence policy. Tool/page-provided strings remain untrusted. Secret handles never become raw secret protocol payloads; only the separately authorized trusted broker-to-browser delivery path may materialize the value, and that value does not pass through MCP, WebMCP, BiDi observation, or model-visible CDP output. Adapter version/provenance is recorded for audit and incident reconstruction. + +## Tests and acceptance evidence + +Require version-negotiation tests, schema/property tests, malformed-message tests, BiDi/CDP semantic parity tests for shared capabilities, WebMCP prompt-injection tests, MCP authority-separation and version-change tests, browser-version compatibility matrices, and end-to-end proof that unsupported capabilities fail without side effects. + +## Migration and rollback + +Adapters are independently versioned and can be canaried. Clients migrate through OriginWeave Protocol compatibility rules, not upstream protocol rewrites. Rollback pins a previously supported adapter/browser/protocol pair and records that pair in provenance. + +## Open follow-ups + +Define internal protocol versioning rules, adapter capability descriptors, minimum supported BiDi level, CDP pin policy, and MCP/WebMCP schema isolation. + +## Supersession / reversal conditions + +Supersede if one mature standard gains all required capabilities, stable compatibility, explicit security semantics, and broad implementation support sufficient to replace the internal abstraction without exposing customers to upstream churn. + +## References + +Chrome DevTools Protocol. (2026). *Chrome DevTools Protocol — latest (tip-of-tree)*. Chromium. Retrieved August 9, 2026, from https://chromedevtools.github.io/devtools-protocol/tot/ + +Chrome DevTools Protocol. (2026). *WebMCP domain*. Chromium. Retrieved August 9, 2026, from https://chromedevtools.github.io/devtools-protocol/tot/WebMCP/ + +Parra, D. S., & Delimarsky, D. (2026, July 28). *The 2026-07-28 specification*. Model Context Protocol Blog. https://blog.modelcontextprotocol.io/posts/2026-07-28/ + +World Wide Web Consortium. (2026, June 29). *WebDriver BiDi* [Working Draft]. https://www.w3.org/TR/2026/WD-webdriver-bidi-20260629/ + +## Related documents + +See `docs/API_CONTRACT.md`, `docs/TRD.md`, `docs/doctoring/product-documentation-baseline.md`, and `docs/DATA_GOVERNANCE.md`. diff --git a/docs/adr/0108-crawler-policy.md b/docs/adr/0108-crawler-policy.md new file mode 100644 index 000000000..71ec67f4e --- /dev/null +++ b/docs/adr/0108-crawler-policy.md @@ -0,0 +1,72 @@ +# ADR 0108: Policy-bound crawler mode + +- Status: Proposed +- Date: 2026-08-09 +- Supersedes: none +- Superseded by: none + +## Context + +Crawler mode lets OriginWeave collect public web content at scale, but scale changes the product's risk profile. A crawler can overload sites, ignore declared exclusion policy, retain excessive personal data, accidentally submit forms, or be pressured to evade anti-automation controls. A provenance-native enterprise runtime must make crawl purpose, rate, robots handling, origin grants, retention, and failure semantics explicit rather than treating crawling as fast navigation. + +## Decision drivers + +- Crawler mode is read-only and purpose-bound. +- robots policy and rate limits must be explicit inputs to execution. +- Network and resource budgets must prevent accidental denial of service. +- Evidence must record crawl purpose and policy decisions. +- CAPTCHA or blocking controls must not be evaded automatically. + +## Assumptions and authority boundaries + +Crawler output and webpage content are untrusted data. Crawl configuration is trusted only when supplied through the control plane by an authorized user or enterprise policy. A site's robots response, rate feedback, HTTP status, or access-control challenge affects permission/degradation but cannot grant capabilities beyond configured policy. RFC 9309 defines a robots-exclusion interoperability protocol; it is not authentication, authorization, or a legal-right oracle. + +## Options considered + +1. Best-effort crawler that retries until content is obtained: rejected because it encourages overload and block evasion. +2. Rely solely on browser defaults and site responses: rejected because purpose, robots, rate, and retention are not explicit enough. +3. Dedicated read-only Crawler mode with policy, robots, rate, resource, and provenance controls: selected. + +## Decision + +Crawler mode is a separate execution mode paired with a public-crawl purpose. It receives explicit origin scope, concurrency and request budgets, per-origin rate limits, robots decision, retention policy, user-agent/product identity policy, and evidence configuration. State-changing typed actions are denied. Redirects and newly resolved destinations are reauthorized through the same network authority model as other navigation. robots disallow or unknown states fail according to configured fail-closed policy rather than being silently ignored. CAPTCHA, challenge, or blocking pages are recorded as blocked/degraded outcomes; OriginWeave does not provide CAPTCHA solving, fingerprint spoofing, residential-proxy rotation, or other block-evasion behavior. + +HTTP retry/backoff behavior remains bounded and typed. A status such as `429 Too Many Requests` can trigger an allowed delay only within the caller's rate/time budget; it cannot authorize indefinite retry, scope expansion, alternate identity, or route evasion. Redirects never inherit crawl or network authority merely because they originated from an allowed page. + +## Consequences + +Some public data will remain unavailable without human or contractual access. Throughput is intentionally bounded. Operators gain predictable controls and provenance for why a URL was or was not collected. Scheduler/resource policy becomes part of crawler correctness. + +## Failure and degraded behavior + +Rate-limit responses back off within bounded policy or stop the affected origin. Unknown robots state, repeated transport failure, authentication challenge, CAPTCHA, or block page does not trigger evasion. Partial crawl output is labeled incomplete and retains reason/evidence. A failure on one origin need not cancel unrelated origins when their budgets and policies remain safe. + +## Security / privacy / governance impact + +Crawler tenancy, purpose, retention, and export are auditable. Collection minimizes unnecessary PII and credentials; authentication is not borrowed from unrelated Human/Assist profiles. Hostile pages cannot turn crawl observations into new targets outside authorized scope. Resource limits reduce abuse and noisy-neighbor risk. Terms, contractual rights, copyright, and privacy obligations remain separate governance inputs; a robots allow rule is not evidence that every collection/use purpose is legally or contractually allowed. + +## Tests and acceptance evidence + +Require RFC 9309-compatible robots parsing/matching tests, allow/disallow/unknown/unavailable-state tests, per-origin rate and bounded backoff tests, redirect reauthorization, cross-origin scope denial, form/write denial, challenge/CAPTCHA no-evasion tests, hostile link expansion tests, tenant/resource isolation, retention/export checks, and provenance assertions for policy decisions. Network tests also cover RFC 9110 HTTP semantics relevant to redirect and rate/degraded behavior. + +## Migration and rollback + +Migrate existing collection flows into explicit Crawler sessions with policy defaults before enabling scale. Rollback may reduce concurrency or disable an origin; it must not fall back to an unconstrained retry/evasion crawler. + +## Open follow-ups + +Define organization-configurable robots policy for ambiguous/unavailable cases, default rate envelopes, crawl-budget APIs, retention classes, and signed crawler identity/contract options for partner sites. + +## Supersession / reversal conditions + +Supersede only if another collection model provides equivalent read-only guarantees, robots/rate/resource controls, no-evasion posture, privacy governance, and provenance under representative hostile-site tests. + +## References + +Fielding, R., Nottingham, M., & Reschke, J. (Eds.). (2022). *HTTP semantics* (RFC 9110). RFC Editor. https://doi.org/10.17487/RFC9110 + +Koster, M., Illyes, G., Zeller, H., & Sassman, L. (2022). *Robots Exclusion Protocol* (RFC 9309). RFC Editor. https://doi.org/10.17487/RFC9309 + +## Related documents + +See ADR 0002, `docs/PRD.md`, `docs/THREAT_MODEL.md`, `docs/OPERABILITY.md`, and `docs/DATA_GOVERNANCE.md`. diff --git a/docs/adr/0109-hourly-automation-operational-closure.md b/docs/adr/0109-hourly-automation-operational-closure.md new file mode 100644 index 000000000..1574efa86 --- /dev/null +++ b/docs/adr/0109-hourly-automation-operational-closure.md @@ -0,0 +1,83 @@ +# ADR 0109: Hourly automation secret ordering and operational closure + +- Status: Proposed +- Date: 2026-08-09 +- Supersedes: none +- Superseded by: none + +## Context + +OriginWeave's hourly product-development workflow can perform deterministic maintenance and, only when appropriate, enter a model-backed development path. A prior incident showed that checking conditions inside a shell branch is insufficient if `NVIDIA_NIM_API_KEY` is already materialized in the step environment. It also showed that nominal fallback sequences are meaningless when their declared runtime exceeds the job budget, retries inherit dirty workspaces, failure classes are collapsed, raw secrets are rematerialized for validation, or a source repair is called complete without protected-main execution evidence. + +## Decision drivers + +- Deterministic gates should require no model credential. +- Secrets are materialized only on the exact path that consumes them. +- Model attempts must start from pristine exact HEAD and fit within the physical job budget. +- Failures need actionable classifications and fail-closed publication behavior. +- Source merge is not sufficient operational-closure evidence. +- Hourly execution must be work-conserving rather than report-as-completion. + +## Assumptions and authority boundaries + +The workflow runner and pinned actions/scripts are trusted only within their declared permissions and egress. Repository content and model output are untrusted change proposals until independently validated. `NVIDIA_NIM_API_KEY` is model-development authority, not a general repository credential. Publication, review, and merge identities remain separate. Protected branch policy is an independent authority. + +## Options considered + +1. Materialize the model secret at job start and conditionally use it later: rejected because unused deterministic paths still receive the credential. +2. Run all maintenance through the model path: rejected because deterministic repository state does not need model authority and availability. +3. Deterministic gate first, conditional secret broker/model path second, independent validation/publication last: selected. + +## Decision + +The hourly workflow executes credential-free deterministic gates first, including open PR, release blocker, dry-run, writer-lease, and feasibility state. An open PR outcome is represented explicitly as `open_pull_request` and stops before model-secret materialization. Only a zero-PR or explicitly eligible development state may enter the credential step that exposes `NVIDIA_NIM_API_KEY` to the loopback broker/model path. Model attempts use pristine exact HEAD, bounded per-attempt and total budgets, and classified failures such as timeout, model/tool failure, broker failure, validation failure, or publication-authority failure. Post-model validation uses credential-free fingerprints/handles rather than rematerializing the raw secret. Missing publication authority for a verified non-empty change fails closed. The single-flight hourly loop returns to other safe work after each blocked item. + +Before automated maintenance completes, it performs a **mandatory exit sweep** over protected main, **open OriginWeave PRs and issues**, current reviews and checks, **release state**, canonical **documentation**, operational acceptance, and buyer-visible **product gaps**. If **safe actionable work remains**, the invocation continues with the highest-value non-conflicting item instead of treating the current result, blocker, documentation update, or queued check as completion. A second fresh sweep is required after any action discovered by the first sweep. Termination is allowed only when practical run budget is exhausted or the second sweep proves every remaining item non-actionable under current authority, dependency, writer lease, repository policy, and safety constraints. + +Repository and job permissions remain least-privilege. Third-party actions and reusable workflows are immutably pinned where repository policy requires it; action pinning does not substitute for reviewing the called workflow's permissions, inputs, secret contract, and source. Secrets are scoped to the smallest consuming job/step path and are never inherited merely for convenience. + +## Consequences + +Model availability no longer blocks deterministic maintenance. Secret exposure is narrower and easier to audit. Fallbacks consume more explicit setup/reset time but are independently attributable. Operational acceptance requires real workflow executions from the integrated protected branch rather than only source-level tests. A single completed action, blocked merge, or documentation repair no longer has run-completion semantics; work is conserved across independent lanes. + +## Failure and degraded behavior + +A deterministic open-PR/release-blocker state exits before credential access and leaves the model path untouched. Broker failure stops model fallback immediately. A model timeout or tool failure may proceed to another pristine attempt only if the broker remains healthy and the remaining job budget is sufficient. Validation or publication failure cannot be converted to success by discarding a non-empty patch. Unknown failure classes fail closed with evidence. A queued check, reviewer delay, provider cooldown, or external prerequisite blocks only that item and is deferred while the exit sweep identifies other safe work. + +## Security / privacy / governance impact + +Harden Runner egress stays fail closed with evidence-backed endpoint sets. The model secret is never replaced with `COPILOT_GITHUB_TOKEN`, guessed PATs, or blanket secret inheritance. Raw secret values are absent from model-visible evidence and post-model scanning. Writer, publication, review, and merge authorities remain separated so automation cannot manufacture independent approval. GitHub's automatic secret redaction is treated as defense in depth rather than proof that transformed or rematerialized values cannot leak. + +## Tests and acceptance evidence + +Repository contracts must verify gate-before-secret ordering, absence of the raw key from deterministic/post-model steps, exact egress, physically schedulable time budgets, pristine fallback reset, bounded model-controlled file reads, classified failures, immutable external action/workflow references where required, least-privilege permissions, and fail-closed publication. + +They must also verify that the mandatory exit sweep inspects protected main, open OriginWeave PRs and issues, reviews, checks, release state, documentation, and product gaps, and that the automation continues whenever safe actionable work remains. A regression must prevent one completed action, blocker, queued check, or documentation update from becoming an implicit run terminator. + +Incident closure additionally requires protected-main scheduled or manual evidence: with an open PR the run reaches `open_pull_request` without materializing `NVIDIA_NIM_API_KEY`; after a later zero-PR state, a run reaches the conditional model path or an explicit deterministic product/release gate; controlled model failure demonstrates classification and pristine retry where feasible. + +## Migration and rollback + +Integrate scheduler changes through normal protected review. Rollback may return to the previous protected workflow only if it preserves deterministic-before-secret ordering, fail-closed egress, authority separation, the mandatory exit sweep, and protected-main evidence. Never roll back to raw-secret rematerialization, broad inherited secrets, unpinned mutable third-party action authority, report-as-completion semantics, or an unschedulable fallback sequence. + +## Open follow-ups + +Collect protected-main acceptance runs after the incident repair merges; maintain runbooks for broker/provider outages; keep reviewer-provisioning governance separate from the workflow's technical correctness; retain machine-checkable exit-sweep coverage as the queue and documentation graph evolve. + +## Supersession / reversal conditions + +Supersede only if a replacement scheduler demonstrates equal or stronger secret minimization, exact-head reset, physical budget feasibility, failure classification, authority separation, work-conserving exit-sweep behavior, and protected-main operational proof. + +## References + +GitHub. (n.d.-a). *Secrets*. GitHub Docs. Retrieved August 9, 2026, from https://docs.github.com/en/actions/concepts/security/secrets + +GitHub. (n.d.-b). *Secure use reference*. GitHub Docs. Retrieved August 9, 2026, from https://docs.github.com/en/actions/reference/security/secure-use + +GitHub. (n.d.-c). *Managing GitHub Actions settings for a repository*. GitHub Docs. Retrieved August 9, 2026, from https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository + +National Institute of Standards and Technology. (2022). *Secure software development framework (SSDF) version 1.1: Recommendations for mitigating the risk of software vulnerabilities* (NIST Special Publication 800-218). https://doi.org/10.6028/NIST.SP.800-218 + +## Related documents + +See `docs/OPERABILITY.md`, `docs/TEST_STRATEGY.md`, `docs/RELEASE_AND_ROLLBACK.md`, `AGENTS.md`, and the hourly product-development workflow and incident repair history. diff --git a/docs/adr/README.md b/docs/adr/README.md new file mode 100644 index 000000000..2838a12a0 --- /dev/null +++ b/docs/adr/README.md @@ -0,0 +1,104 @@ +# OriginWeave Architecture Decision Index + +This directory contains durable architecture decisions for OriginWeave. A pull-request body, chat transcript, roadmap bullet, or implementation plan may motivate a decision but does not replace an ADR when the decision changes a governing product or authority boundary. + +## Status vocabulary + +- **Proposed** — under review; not binding and not a shipped claim. +- **Accepted** — governing design decision on protected `main`; acceptance does not by itself prove that every described capability is implemented. +- **Superseded** — replaced by a later Accepted ADR; retained for history. +- **Deprecated** — still discoverable but no longer recommended for new work. +- **Rejected** — evaluated and intentionally not adopted. + +An ADR becomes Accepted only through normal protected-branch review and merge. Where live repository policy or explicit CWL/OriginWeave governance requires independent review, acceptance also requires a qualifying non-author formal `APPROVED` review on the unchanged exact head. COMMENTED reviews, check/status results, model verdicts, reactions, author approval, predecessor-head approval, or dismissed reviews never substitute for that requirement. Conversation-derived ideas remain Proposed/Open in PRD/TRD/traceability until the protected process is complete. + +An Accepted ADR is **design authority, not implementation evidence**. Protected-main source, executable tests, built/released artifacts, migrations/configuration, and protected-main operational evidence appropriate to the claim establish current implemented behavior. An ADR may intentionally describe an accepted target that is only partially implemented; the product documents must label that implementation status separately. + +## Current protected-main decisions + +| ADR | Decision | Protected-main status | Governs | +|---|---|---|---| +| [0001](0001-chromium-compatibility-kernel.md) | Retain Chromium as the compatibility kernel | Accepted | Blink/V8/graphics/extensions boundary; Rust control-plane integration | +| [0002](0002-agent-safety-kernel.md) | Agent safety kernel | Accepted | mode, capability, origin, risk, crawler, secret and approval policy | +| [0003](0003-provenance-native-observation.md) | Provenance-native observation | Accepted | evidence/provenance as a first-class product output | +| [0004](0004-resolved-destination-policy.md) | Logical origin and resolved destination safety | Accepted | SSRF/rebinding/special-purpose address and redirect authority | +| [0005](0005-direct-socket-binding.md) | Exact direct TCP peer binding | Accepted | explicit socket authority and operating-system peer proof | +| [0006](0006-tls-server-identity.md) | TLS service identity over the verified peer | Accepted | WebPKI identity, roots, time, ALPN and stream binding | + +## Proposed target-architecture decisions in this change + +The following ADRs make the product-wide target architecture reviewable without promoting it to shipped behavior. They remain **Proposed** until their exact branch is reviewed and merged under protected-main policy. Existing feature PRs may independently carry lower-numbered Proposed ADRs; the `0100` range avoids claiming or conflicting with those active decisions. + +| ADR | Decision | Status | Governs | +|---|---|---|---| +| [0100](0100-rust-control-plane-boundary.md) | Rust control-plane boundary | Proposed | Rust-owned product authority versus Chromium compatibility kernel | +| [0101](0101-isolated-execution-profile-modes.md) | Isolated execution/profile modes | Proposed | Human, Assist, Agent Task and Crawler session/profile isolation | +| [0102](0102-typed-actions-and-arbitrary-js.md) | Typed actions over arbitrary JavaScript authority | Proposed | action API, script escape hatches, risk/policy semantics | +| [0103](0103-semantic-observation-and-stale-node-identity.md) | Semantic observation precedence and stale-node identity | Proposed | WebMCP/structured/accessibility/DOM/layout/visual precedence and document epochs | +| [0104](0104-prompt-injection-and-secret-authority.md) | Prompt-injection and secret authority separation | Proposed | untrusted page data, opaque secret handles and broker boundaries | +| [0105](0105-resource-governor-priority.md) | Resource governor and browser-over-model priority | Proposed | CPU/RAM/GPU/VRAM admission, fallback and tenant fairness | +| [0106](0106-provenance-evidence-model.md) | Provenance-native evidence model | Proposed | WARC/PROV-style evidence identities, integrity and disclosure | +| [0107](0107-browser-protocol-adapter-strategy.md) | Versioned browser and agent protocol adapters | Proposed | WebDriver BiDi, CDP, WebMCP, MCP and OriginWeave Protocol boundaries | +| [0108](0108-crawler-policy.md) | Policy-bound crawler mode | Proposed | robots, rate/resource policy, read-only collection and no-evasion behavior | +| [0109](0109-hourly-automation-operational-closure.md) | Hourly automation secret ordering and operational closure | Proposed | deterministic gates, model secret boundary, retries and protected-main proof | + +Active feature PRs may contain additional Proposed ADRs. Those ADRs are not described as Accepted until their exact changes merge. When an ADR becomes protected-main architecture, update this index in the same protected change or an immediately coupled documentation repair. + +## Decisions that require a dedicated ADR + +A new or superseding ADR is required when a change materially alters any of the following: + +1. Chromium compatibility-kernel ownership or patch strategy; +2. execution modes or autonomous profile/session isolation; +3. trusted-instruction, untrusted-observation or protected-secret boundaries; +4. capability, action, risk or approval semantics; +5. logical origin, resolved destination, route/proxy, TCP peer, TLS identity or HTTP authority; +6. browser session/context/document/node lifetime and stale-reference semantics; +7. sensitive-data authority, opaque-handle broker or disclosure evidence; +8. observation hierarchy or arbitrary-script policy; +9. resource-governor priority, telemetry or GPU/CPU fallback semantics; +10. evidence/provenance identity, retention or persistence boundaries; +11. WebDriver BiDi, CDP, WebMCP, MCP or OriginWeave Protocol authority/version boundaries; +12. Manifest V3 extension-to-agent authorization; +13. tenant, privacy, residency, audit, deployment or enterprise-control ownership; +14. release acceptance, rollback/recovery or protected-main operational-proof requirements. + +## Required ADR structure + +New material ADRs should contain the following sections unless a section is demonstrably inapplicable: + +```text +# ADR NNNN: Decision title + +- Status: Proposed | Accepted | Superseded | Deprecated | Rejected +- Date: YYYY-MM-DD +- Supersedes: optional ADR reference +- Superseded by: optional ADR reference + +## Context +## Decision drivers +## Assumptions and authority boundaries +## Options considered +## Decision +## Consequences +## Failure and degraded behavior +## Security / privacy / governance impact +## Tests and acceptance evidence +## Migration and rollback +## Open follow-ups +## Supersession / reversal conditions +## References +``` + +Material external standards or research belong in APA 7th format in [`../doctoring.md`](../doctoring.md) and may also be repeated in the ADR when the citation is necessary to understand the decision. + +## Relationship to product documents + +- [`../PRD.md`](../PRD.md) defines buyer and product requirements. +- [`../TRD.md`](../TRD.md) translates them into technical invariants and implementation-status boundaries. +- [`../../ARCHITECTURE.md`](../../ARCHITECTURE.md) defines system topology and bounded contexts. +- [`../uml/README.md`](../uml/README.md) visualizes component, sequence, state and deployment relationships. +- [`../erd/README.md`](../erd/README.md) defines the conceptual durable domain model. +- [`../traceability/README.md`](../traceability/README.md) maps requirements and decisions to implementation and evidence. + +If these artifacts disagree about what is currently implemented, protected-main source, executable tests, built/released artifacts, configuration/migrations, and protected-main operational evidence appropriate to the claim define implementation truth. Accepted ADRs explain the governing design decision and expected boundary; they do not upgrade missing behavior into shipped behavior. The disagreement is a documentation or implementation defect that must be repaired rather than silently rationalized from conversation history. diff --git a/docs/doctoring/product-documentation-baseline.md b/docs/doctoring/product-documentation-baseline.md new file mode 100644 index 000000000..3ba7f955a --- /dev/null +++ b/docs/doctoring/product-documentation-baseline.md @@ -0,0 +1,91 @@ +# Product Documentation Baseline — Research and Standards Doctoring + +- **Reviewed:** 2026-08-09 +- **Purpose:** Fresh primary-source evidence for the PRD/TRD/UML/ERD/data-governance documentation baseline +- **Relationship:** Supplements [`../doctoring.md`](../doctoring.md); it does not supersede the deeper network/TLS/research bibliography there. + +This addendum exists because product-level documentation introduced explicit interoperability, accessibility, data-governance, and assurance-status claims that need a current evidence snapshot. The production design still requires feature-specific evidence in the governing ADR and main doctoring document. + +## WebDriver BiDi + +The W3C latest published WebDriver BiDi document reviewed for this baseline is a **Working Draft dated 29 June 2026**. It defines a bidirectional browser automation protocol and links to an implementation report and Web Platform Tests. Because it is still a Working Draft, OriginWeave keeps it behind a versioned adapter and conformance tests instead of making its object identifiers or protocol semantics the core authority model. + +**Product implication:** `OriginWeave Protocol` remains the internal stable boundary; WebDriver BiDi is a replaceable/versioned adapter. + +## Chrome DevTools Protocol and WebMCP + +The Chrome DevTools Protocol tip-of-tree documentation states that the latest protocol changes frequently, may break at any time, and does not guarantee backwards compatibility for new capabilities. The reviewed tip-of-tree snapshot was updated on 8 August 2026. + +The same tip-of-tree documentation exposes a **WebMCP** domain and marks it **Experimental**. The domain supports tool registration/invocation lifecycle events and explicitly warns that tool output is untrusted and may contain prompt-injection content; its annotations include `readOnly` and `untrustedContent` hints. + +**Product implications:** + +- CDP-specific capability remains behind a versioned Chromium adapter. +- WebMCP is a preferred typed observation/tool channel when available, not the sole observation path. +- WebMCP tool descriptions, inputs and outputs are page-originated untrusted data; annotations cannot create OriginWeave capabilities or approval. +- A tip-of-tree CDP feature cannot become a release requirement without a supported-version matrix and fallback/compatibility evidence. + +## Chrome Manifest V3 + +Chrome's current extension documentation identifies Manifest V3 as the current extension platform baseline. The migration documentation also notes that Manifest V3 removes remotely hosted code so extension JavaScript is packaged and reviewable with the extension. + +**Product implication:** OriginWeave preserves Chromium's Manifest V3 implementation and tests compatibility rather than creating a separate default Rust plugin ecosystem that would require reimplementing Chrome extension APIs. OriginWeave agent authority remains a separate signed policy grant rather than an implicit extension permission. + +## WCAG 2.2 and ISO/IEC 40500:2025 + +WCAG 2.2 is a W3C Recommendation. W3C announced on 21 October 2025 that WCAG 2.2 was approved as **ISO/IEC 40500:2025**. W3C notes that the ISO publication corresponds to the October 2023 WCAG 2.2 version while W3C continues to maintain later errata/updates. + +**Product implication:** OriginWeave product UI uses WCAG 2.2 AA as its accessibility design target and tracks current W3C errata. References to ISO/IEC 40500:2025 describe the international-standard alignment; they do not constitute product certification or conformance by themselves. + +## NIST AI 600-1 + +NIST AI 600-1, *Artificial Intelligence Risk Management Framework: Generative Artificial Intelligence Profile*, remains the primary NIST generative-AI profile used by this product baseline. + +**Product implication:** OriginWeave uses NIST AI 600-1 as risk-management input for model/provider, untrusted-content, evaluation, provenance and lifecycle controls. It is not a certification claim and cannot substitute for deterministic browser authority or application-specific threat analysis. + +## NIST zero-trust architecture and data access + +NIST SP 800-207 states that zero trust grants no implicit trust based solely on physical/network location or asset ownership and focuses authorization on resources. NIST SP 800-207A extends the model to cloud-native and multi-location applications and explicitly emphasizes application/service identity plus granular application-level authorization policy. + +**Product implications:** + +- Sensitive-data disclosure is a resource-access decision, not an ambient consequence of being inside the network or browser session. +- Tenant, task, field, purpose, destination, classification, service identity, and current policy state are independent authorization dimensions where applicable. +- A trusted broker or browser adapter rechecks authority immediately before disclosure instead of treating a previously issued opaque handle as transferable bearer authority. +- Service-to-service paths must authenticate workload/service identity and prevent confused-deputy disclosure. + +## KISA CSAP assurance boundary + +KISA's current CSAP program description states that the certification applies to cloud computing services evaluated against the applicable cloud security certification criteria and that the certification mark is for services that have actually obtained certification. + +**Product implication:** OriginWeave may design features and evidence for CSAP readiness, but source code, tests, or a control mapping cannot truthfully claim that a deployed service is CSAP certified. Certification claims remain bound to the assessed service boundary and current program requirements. + +## AICPA Trust Services Criteria assurance boundary + +The AICPA 2017 Trust Services Criteria with revised 2022 points of focus provide criteria for evaluating controls relevant to security, availability, processing integrity, confidentiality, and privacy in attestation or consulting engagements. + +**Product implication:** OriginWeave uses the criteria as a control/evidence design input. Product capability, configured control, operating control, collected evidence, management assertion, and independent examination result remain distinct evidence classes. Documentation must not collapse them into a generic “SOC 2 compliant” claim. + +## APA 7th references + +American Institute of Certified Public Accountants. (2023). *2017 trust services criteria for security, availability, processing integrity, confidentiality, and privacy (with revised points of focus—2022)*. AICPA & CIMA. https://www.aicpa-cima.com/resources/download/2017-trust-services-criteria-with-revised-points-of-focus-2022 + +Chandramouli, R., & Butcher, Z. (2023). *A zero trust architecture model for access control in cloud-native applications in multi-location environments* (NIST Special Publication 800-207A). National Institute of Standards and Technology. https://doi.org/10.6028/NIST.SP.800-207A + +Chrome for Developers. (n.d.). *Extensions / Manifest V3*. Google. Retrieved August 9, 2026, from https://developer.chrome.com/docs/extensions/develop/migrate/what-is-mv3 + +Chrome DevTools Protocol. (2026). *Chrome DevTools Protocol — latest (tip-of-tree)*. Chromium. Retrieved August 9, 2026, from https://chromedevtools.github.io/devtools-protocol/tot/ + +Chrome DevTools Protocol. (2026). *WebMCP domain*. Chromium. Retrieved August 9, 2026, from https://chromedevtools.github.io/devtools-protocol/tot/WebMCP/ + +Korea Internet & Security Agency. (n.d.). *클라우드 보안인증제 제도소개*. Retrieved August 9, 2026, from https://isms.kisa.or.kr/main/csap/intro/index.jsp + +National Institute of Standards and Technology. (2024). *Artificial intelligence risk management framework: Generative artificial intelligence profile* (NIST AI 600-1). https://doi.org/10.6028/NIST.AI.600-1 + +Rose, S., Borchert, O., Mitchell, S., & Connelly, S. (2020). *Zero trust architecture* (NIST Special Publication 800-207). National Institute of Standards and Technology. https://doi.org/10.6028/NIST.SP.800-207 + +World Wide Web Consortium. (2023). *Web Content Accessibility Guidelines (WCAG) 2.2*. https://www.w3.org/TR/WCAG22/ + +World Wide Web Consortium. (2025, October 21). *W3C Web Content Accessibility Guidelines 2.2 approved as ISO/IEC international standard*. https://www.w3.org/press-releases/2025/wcag22-iso-pas/ + +World Wide Web Consortium. (2026, June 29). *WebDriver BiDi* [Working Draft]. https://www.w3.org/TR/2026/WD-webdriver-bidi-20260629/ diff --git a/docs/erd/README.md b/docs/erd/README.md new file mode 100644 index 000000000..895053cb0 --- /dev/null +++ b/docs/erd/README.md @@ -0,0 +1,536 @@ +# OriginWeave Conceptual ERD and Durable Domain Model + +- **Status:** Proposed authoritative logical model +- **Persistence status:** Conceptual unless a specific adapter/schema is marked Implemented elsewhere +- **Naming:** Descriptive two-or-more-word `snake_case` +- **Technical requirements:** [`../TRD.md`](../TRD.md) + +This model exists even though OriginWeave does not yet implement every entity as a relational table. It prevents session, authority, evidence, provenance, resource, and secret concepts from being silently collapsed when persistence adapters are introduced. + +## 1. Persistence truth + +The following distinction is mandatory: + +- **Implemented value/evidence concept** — represented by current Rust code, but not necessarily durably persisted. +- **Planned durable record** — conceptual entity required for future headless/browser/enterprise persistence. +- **Adapter-owned representation** — may live in relational storage, WARC, object storage, PROV serialization, or another versioned adapter. + +The ERD does **not** authorize direct cross-service database access. Other CWL products integrate through versioned APIs/events/artifacts rather than querying OriginWeave application tables. + +## 2. Conceptual ERD + +```mermaid +erDiagram + tenant_record ||--o{ browser_profile : owns + tenant_record ||--o{ agent_session : owns + tenant_record ||--o{ extraction_schema : governs + browser_profile ||--o{ agent_session : supplies + agent_session ||--o{ browsing_context : contains + browsing_context ||--o{ page_snapshot : produces + page_snapshot ||--o{ semantic_node : contains + + agent_session ||--o{ action_intent : scopes + semantic_node o|--o{ action_intent : targets + action_intent ||--o{ policy_decision : evaluated_by + action_intent ||--o{ approval_evidence : may_require + action_intent ||--o{ action_event : executes_as + action_event ||--o{ postcondition_evidence : verifies + + agent_session ||--o{ origin_authority : grants + origin_authority ||--o{ resolution_snapshot : resolves_to + resolution_snapshot ||--o{ route_decision : routes + route_decision ||--o{ connection_evidence : connects + connection_evidence ||--o{ tls_identity_evidence : authenticates + tls_identity_evidence ||--o{ http_exchange : carries + http_exchange ||--o{ network_exchange : records + + agent_session ||--o{ sensitive_authority : scopes + sensitive_authority ||--o{ secret_handle : authorizes + secret_handle ||--o{ access_receipt : records_use + action_event o|--o{ access_receipt : consumes + + agent_session ||--|| resource_budget : governed_by + agent_session ||--o{ resource_snapshot : observes + resource_budget ||--o{ mitigation_plan : derives + resource_snapshot ||--o{ mitigation_plan : informs + + page_snapshot o|--o{ source_resource : may_reference + network_exchange o|--o{ source_resource : may_capture + source_resource ||--o{ content_record : materializes + content_record ||--o{ extracted_value : supports + extraction_schema ||--o{ extracted_value : constrains + semantic_node o|--o{ extracted_value : supports + + provenance_record ||--|{ provenance_link : contains + source_resource o|--o{ provenance_link : may_target + content_record o|--o{ provenance_link : may_target + extracted_value o|--o{ provenance_link : may_target + action_event o|--o{ provenance_link : may_target + policy_decision o|--o{ provenance_link : may_target + postcondition_evidence o|--o{ provenance_link : may_target + + agent_session ||--o{ task_checkpoint : checkpoints + agent_session ||--o{ download_artifact : produces + source_resource o|--o{ download_artifact : originates + tenant_record ||--o{ extension_grant : governs + browser_profile ||--o{ extension_grant : applies + + tenant_record { + string tenant_record_id PK + string policy_version + string residency_profile + string lifecycle_state + } + + browser_profile { + string browser_profile_id PK + string tenant_record_id FK + string profile_class + string isolation_mode + } + + agent_session { + string agent_session_id PK + string tenant_record_id FK + string browser_profile_id FK + string session_mode + string execution_purpose + string lifecycle_state + } + + browsing_context { + string browsing_context_id PK + string agent_session_id FK + string context_kind + string canonical_origin + integer document_epoch + } + + page_snapshot { + string page_snapshot_id PK + string browsing_context_id FK + integer document_epoch + string snapshot_digest + string captured_at + } + + semantic_node { + string semantic_node_id PK + string page_snapshot_id FK + string role_code + string accessible_name_digest + string authority_digest + } + + action_intent { + string action_intent_id PK + string agent_session_id FK + string semantic_node_id FK + string action_kind + string target_origin + string intent_digest + string risk_class + } + + policy_decision { + string policy_decision_id PK + string action_intent_id FK + string policy_version + string decision_code + string decided_at + } + + approval_evidence { + string approval_evidence_id PK + string action_intent_id FK + string approval_kind + string approved_intent_digest + string approved_at + string expires_at + } + + action_event { + string action_event_id PK + string action_intent_id FK + string attempt_state + string started_at + string completed_at + } + + postcondition_evidence { + string postcondition_evidence_id PK + string action_event_id FK + string expectation_kind + string verification_state + string observed_at + } + + origin_authority { + string origin_authority_id PK + string agent_session_id FK + string canonical_origin + string capability_scope + string expires_at + } + + resolution_snapshot { + string resolution_snapshot_id PK + string origin_authority_id FK + string address_set_digest + integer address_count + string approved_at + } + + route_decision { + string route_decision_id PK + string resolution_snapshot_id FK + string route_kind + string proxy_origin + string pac_origin + } + + connection_evidence { + string connection_evidence_id PK + string route_decision_id FK + string requested_socket + string observed_socket + integer attempt_number + } + + tls_identity_evidence { + string tls_identity_evidence_id PK + string connection_evidence_id FK + string canonical_origin + string reference_identity + string trust_bundle_digest + string tls_version + } + + http_exchange { + string http_exchange_id PK + string tls_identity_evidence_id FK + string method_code + integer status_code + string framing_state + string integrity_state + } + + network_exchange { + string network_exchange_id PK + string http_exchange_id FK + string canonical_origin + string bounded_path + string captured_at + } + + sensitive_authority { + string sensitive_authority_id PK + string agent_session_id FK + string field_identifier + string purpose_code + string destination_origin + string data_classification + } + + secret_handle { + string secret_handle_id PK + string sensitive_authority_id FK + string handle_state + integer maximum_uses + string expires_at + } + + access_receipt { + string access_receipt_id PK + string secret_handle_id FK + string action_event_id FK + string decision_outcome + string policy_version + string retention_until + } + + resource_budget { + string resource_budget_id PK + string agent_session_id FK + integer cpu_worker_limit + integer ram_byte_limit + integer vram_byte_limit + integer network_concurrency_limit + integer evidence_cache_byte_limit + integer artifact_storage_byte_limit + integer file_descriptor_limit + integer queue_entry_limit + string browser_process_priority + string model_process_priority + string budget_version + } + + resource_snapshot { + string resource_snapshot_id PK + string agent_session_id FK + integer cpu_worker_count + integer ram_bytes + integer vram_bytes + integer network_active_count + integer evidence_cache_bytes + integer artifact_storage_bytes + integer file_descriptor_count + integer queue_entry_count + string observed_at + } + + mitigation_plan { + string mitigation_plan_id PK + string resource_budget_id FK + string resource_snapshot_id FK + boolean reject_admission + boolean pause_agent + boolean reduce_model_batch + boolean offload_model + boolean spill_evidence_cache + } + + source_resource { + string source_resource_id PK + string page_snapshot_id FK "nullable" + string network_exchange_id FK "nullable" + string source_kind + string source_locator + string content_digest + } + + content_record { + string content_record_id PK + string source_resource_id FK + string content_kind + string media_type + string content_digest + integer content_bytes + string retention_class + } + + extraction_schema { + string extraction_schema_id PK + string tenant_record_id FK + string schema_name + string schema_version + string schema_digest + string lifecycle_state + } + + extracted_value { + string extracted_value_id PK + string content_record_id FK + string extraction_schema_id FK + string semantic_node_id FK "nullable" + string field_name + string value_digest + string verification_state + } + + provenance_record { + string provenance_record_id PK + string provenance_digest + string schema_version + string created_at + } + + provenance_link { + string provenance_link_id PK + string provenance_record_id FK + string target_kind + string target_identifier + string relation_kind + integer sequence_number + } + + task_checkpoint { + string task_checkpoint_id PK + string agent_session_id FK + string checkpoint_digest + string created_at + string recovery_state + } + + download_artifact { + string download_artifact_id PK + string agent_session_id FK + string source_resource_id FK + string content_digest + string mime_state + integer artifact_bytes + } + + extension_grant { + string extension_grant_id PK + string tenant_record_id FK + string browser_profile_id FK + string extension_identifier + string capability_scope + string grant_state + } +``` + +## 3. Core aggregate boundaries + +### Session aggregate + +Root: `agent_session` + +Owns or scopes: + +- `browser_profile` association; +- `browsing_context`; +- task mode/purpose; +- `resource_budget`; +- `task_checkpoint`; +- task-scoped origin and sensitive authority. + +A session does not imply network, secret, or action permission by itself. + +### Observation aggregate + +Root: `page_snapshot` + +Owns: + +- exact `document_epoch`; +- `semantic_node` values; +- source references; +- snapshot digest and observation time. + +A node is never a global primary key for browser state; its authority is meaningful only with the session/context/origin/document lifetime represented by the adapter/core contract. + +### Action aggregate + +Root: `action_intent` + +Links: + +- exact typed intent and digest; +- deterministic `policy_decision`; +- optional `approval_evidence`; +- one or more execution `action_event` attempts; +- resulting `postcondition_evidence`. + +Approval and execution evidence are separate records because approval does not prove that the action ran and an action event does not prove the expected outcome occurred. + +### Network authority aggregate + +The sequence is intentionally decomposed: + +```text +origin_authority +-> resolution_snapshot +-> route_decision +-> connection_evidence +-> tls_identity_evidence +-> http_exchange +-> network_exchange +``` + +No downstream record retroactively grants an upstream authority. + +### Sensitive-data aggregate + +```text +sensitive_authority +-> secret_handle +-> access_receipt +``` + +The protected value is deliberately absent from the conceptual audit entities. Storage adapters may need encrypted secret material, but that material belongs to a dedicated trusted secret store rather than general evidence tables. + +### Resource-governance aggregate + +`resource_budget` is scoped to exactly one `agent_session` in this conceptual model. `cpu_worker_limit` means the count of OriginWeave-controlled CPU compute workers/admitted execution slots; it is not a percentage of total host CPU and does not govern Chromium's internal scheduler. The budget also carries RAM, VRAM, network-concurrency, evidence-cache, artifact-storage, file-descriptor, queue, and browser/model-priority limits. `resource_snapshot` measures the same auditable dimensions, and a `mitigation_plan` binds one budget plus one observed snapshot to concrete admission/pause/batch/offload/cache actions. + +Tenant-wide or host-wide quotas require separate versioned policy entities rather than overloading one session budget. + +### Content and extraction aggregate + +```text +source_resource +-> content_record +-> extracted_value +extraction_schema +-> extracted_value +``` + +`source_resource` identifies where evidence came from; `content_record` identifies a bounded retained representation of that source; `extraction_schema` identifies the versioned contract used to interpret content; and `extracted_value` records a derived field without pretending that its digest is the source itself. + +A `source_resource` may link to **zero or one** `page_snapshot` and **zero or one** `network_exchange`; neither link is universally mandatory. The valid combination depends on `source_kind`: a DOM/accessibility/screenshot source normally binds a page snapshot, an HTTP body or WARC member normally binds a network exchange, a source reconstructed from both may bind both, and an approved external/file source can bind neither when its versioned locator/content identity supplies the source authority. Adapters must validate the allowed combination for each `source_kind` rather than manufacture a fake page or network parent. + +A screenshot, HTTP body, DOM-derived record, WARC member, or download may therefore have separate storage/export representations while keeping one conceptual source/content/extraction lineage. Protected secrets do not become `content_record` payloads merely because a page used them. + +### Evidence/provenance aggregate + +```text +provenance_record +-> one-or-more provenance_link +provenance_link +-> typed source/evidence target +``` + +`provenance_record` does not require every possible evidence parent. Instead it has one or more typed `provenance_link` records whose `target_kind`, `target_identifier`, and `relation_kind` identify the actual lineage edge. Supported targets may include `source_resource`, `content_record`, `extracted_value`, `action_event`, `policy_decision`, and `postcondition_evidence`; a versioned schema defines the allowed target kinds and relation kinds. This avoids fake/null-filled relationships while allowing extraction-only, action-only, or combined provenance. + +A physical relational adapter may implement typed association tables instead of one polymorphic table when stronger foreign-key enforcement is desired. In either representation, an adapter must reject unknown target kinds and dangling targets. The extraction schema is an independent versioned authority for interpretation and does not merge with source-content identity or provenance truth. + +## 4. Identity rules + +- Durable IDs are opaque and nonnumeric where practical. +- Adapter-local CDP/WebDriver/node/process identifiers are not durable core identifiers. +- Digests are content/intent/evidence identifiers, not authorization by themselves. +- A canonical origin string is a logical identity, not a database key for authorization state. +- A `secret_handle_id` is opaque authority reference metadata, never the protected value. +- `source_resource_id`, `content_record_id`, `extraction_schema_id`, and `extracted_value_id` remain separate so storage identity, interpretation contract, and derived-value identity cannot collapse into one identifier. + +## 5. Temporal rules + +Persisted event/evidence records use trusted server/runtime times appropriate to the boundary. Client/page timestamps may be captured as data but are not authoritative for expiry, approval, secret use, or policy transitions. + +At minimum, future durable task implementations distinguish: + +- event occurrence/start/end time when known; +- runtime observation/decision time; +- external-page supplied time as untrusted source data; +- retention/expiry time; +- model/provider completion time where relevant. + +## 6. Privacy and retention rules + +- Evidence defaults to data minimization and universal redaction for generic network values. +- Protected values are not duplicated into audit/provenance tables or ordinary `content_record` payloads. +- Tenant/resource authorization applies before record access, not after retrieval. +- Retention is purpose/classification aware and can differ between source metadata, retained content, derived values, and accountability records. +- Export and deletion operations preserve integrity/accountability records only to the extent required by the governing policy or law; the exact enterprise lifecycle remains Planned. + +See [`../DATA_GOVERNANCE.md`](../DATA_GOVERNANCE.md) for field-scoped disclosure, opaque-handle, model/provider, retention/deletion/residency, and assurance boundaries. + +## 7. Adapter mapping guidance + +A relational adapter might persist `agent_session`, policy/action metadata, extraction schema metadata, and indexes. WARC may persist eligible source/content protocol material. Object storage may hold screenshots/downloads or larger `content_record` payloads. PROV serialization may represent derivation. These are parallel representations of bounded concepts, not permission to duplicate secrets or bypass data-minimization rules. + +## 8. ERD change control + +Update this file when an Accepted or implemented change alters: + +- durable entity identity or ownership; +- session/context/document lifetime; +- action/approval/post-condition relationships; +- network authority sequence; +- sensitive-data handle lifecycle; +- content/extraction schema lineage; +- resource-governor evidence; +- provenance derivation; +- tenant/extension governance. + +A new database table alone does not justify changing the conceptual model if it is an implementation detail; conversely, a new durable domain concept must appear here even if its persistence adapter is not yet implemented. + +## References + +International Organization for Standardization. (2017). *Information and documentation—WARC file format* (ISO 28500:2017). https://www.iso.org/standard/68004.html + +Lebo, T., Sahoo, S., & McGuinness, D. (Eds.). (2013). *PROV-O: The PROV ontology* (W3C Recommendation). World Wide Web Consortium. https://www.w3.org/TR/prov-o/ + +Moreau, L., & Missier, P. (Eds.). (2013). *PROV-DM: The PROV data model* (W3C Recommendation). World Wide Web Consortium. https://www.w3.org/TR/prov-dm/ diff --git a/docs/traceability/README.md b/docs/traceability/README.md new file mode 100644 index 000000000..3d5a298e3 --- /dev/null +++ b/docs/traceability/README.md @@ -0,0 +1,152 @@ +# OriginWeave Product and Decision Traceability + +- **Status:** Proposed authoritative traceability baseline +- **Scope:** Product requirements, Accepted architecture, implemented kernels, planned adapters, conversation-derived decisions, standards, and verification evidence + +This file prevents two opposite errors: + +1. an implemented safety boundary becoming undiscoverable because it exists only in code/tests; and +2. a product-design conversation or pull-request proposal being presented as if it already shipped. + +## 1. Evidence precedence + +For current behavior, use this precedence order: + +1. exact protected-main code and executable tests; +2. Accepted ADRs governing that code; +3. current root `ARCHITECTURE.md` and authoritative PRD/TRD aligned to protected main; +4. roadmap and issue/PR plans; +5. conversation-derived product decisions and research notes. + +Lower layers may define future direction but cannot override current protected implementation or an Accepted ADR. + +## 2. Status vocabulary + +- **Implemented** — present on protected `main` with executable evidence. +- **Accepted architecture** — governing reviewed direction, though the complete runtime path may be unfinished. +- **Proposed** — candidate product/design decision requiring reviewed adoption. +- **Open** — intentionally unresolved. + +A change can move from Proposed -> Accepted architecture -> Implemented, but never skips evidence merely because the idea is compelling. + +## 3. Product-level decision trace + +| Product decision | Origin/status | Authoritative artifact | Protected implementation/evidence | +|---|---|---|---| +| Chromium remains the compatibility kernel rather than rewriting Blink/V8 | Accepted architecture | ADR 0001; `ARCHITECTURE.md`; PRD-COMP-001 | Architecture/repository contract tests; Chromium adapter itself remains Planned | +| `Browse. Act. Prove.` provenance-native product identity | Accepted product framing | `README.md`; `docs/PRD.md`; roadmap | Evidence/provenance foundation implemented; full buyer Evidence Trail Planned | +| Human / Assist / Agent Task / Crawler execution modes | Accepted architecture | `ARCHITECTURE.md`; `docs/PRD.md`; ADR 0002 | Core mode/purpose and policy foundation implemented; browser-session integration Planned | +| Page content is data, never instruction authority | Implemented foundation | ADR 0002; `ARCHITECTURE.md`; `docs/TRD.md` | `originweave-core` + `originweave-policy` tests | +| Typed actions instead of default arbitrary JavaScript | Accepted architecture | PRD-ACT-001..004; ADR 0002 | Typed core/policy foundation implemented; full browser action adapter Planned | +| logical origin != resolved destination | Implemented | ADR 0004; TRD-INV-002 | `originweave-destination`; destination governance tests | +| resolved destination != TCP peer | Implemented | ADR 0005; TRD Section 6 | `originweave-network`; loopback/peer tests | +| TCP peer != TLS service identity | Implemented | ADR 0006; TRD Section 6 | `originweave-tls`; rustls integration tests | +| Proxy/PAC route authority must be explicit | Accepted architecture / active development | PRD-NET-005; TRD Section 6.3 | Protected-main direct-only boundary exists; complete proxy execution not yet shipped | +| HTTP semantics require an authenticated governed connection and resource bounds | Accepted architecture / active development | PRD-NET-006; TRD Section 6.6 | Not yet a protected-main product capability in this baseline | +| Node handles bind session/context/origin/document lifetime | Proposed/active development | PRD-OBS-001/002; TRD Section 5 | Not treated as shipped until protected integration | +| Raw secrets never enter model context | Accepted architecture / implemented policy foundation | PRD-DATA-001; ADR 0002; TRD Section 9 | Core secret-delivery policy implemented; trusted broker runtime Planned | +| Sensitive disclosure is purpose-bound and classification-bound | Proposed/active development | PRD-DATA-002; TRD Section 9 | Do not claim complete broker/service until protected integration | +| Evidence/provenance are product outputs, not debug leftovers | Accepted / foundation implemented | ADR 0003; PRD Section 9.6 | `originweave-evidence`; evidence governance tests | +| Human interaction outranks inference/background collection | Accepted architecture / foundation implemented | `ARCHITECTURE.md`; PRD-RES-002 | Deterministic resource mitigation foundation implemented; platform telemetry Planned | +| Structured observation precedes raw HTML/screenshot fallback | Accepted architecture | PRD-OBS-003; TRD Section 7 | Observation adapter Planned | +| WebDriver BiDi / CDP / WebMCP / MCP are adapters, not internal authority | Accepted architecture | PRD Section 9.8; TRD Section 12 | Adapter implementations Planned | +| Manifest V3 compatibility is preserved upstream where practical | Accepted architecture | ADR 0001; PRD Section 9.9 | Chromium compatibility program Planned | +| WARC/PROV-oriented durable evidence adapters | Accepted architecture / Planned | ADR 0003; PRD-EVD-005 | Source/provenance kernel foundation exists; persistence adapters Planned | +| Origin Map visualizes value/action provenance | **conversation-derived Proposed** product UX | PRD-EVD-004; this traceability record | No shipped UI claim | +| Browser / Runtime / Observe / Capture / Governor / Policy / Evidence / Protocol / SDK product surfaces | **conversation-derived Proposed product taxonomy**, aligned to existing architecture | PRD Section 6 | Some foundations exist under crates; named commercial surfaces are not all shipped artifacts | +| Constrained GPU phase scheduling for browser rendering vs local inference | **conversation-derived Accepted architecture direction**, implementation Planned | PRD-RES-005; TRD Section 10 | Deterministic resource plan exists; real GPU scheduler/telemetry Planned | +| Enterprise SSO/SCIM/residency/audit/procurement package | Planned | PRD Section 9.11; roadmap Phase 5 | Not shipped in pre-alpha baseline | + +## 4. Requirement-to-module trace + +| Requirement family | Current module(s) | Primary tests/docs | Implementation status | +|---|---|---|---| +| Canonical origin / action / approval | `originweave-core` | crate tests; ADR 0002 | Implemented | +| Deterministic action policy | `originweave-policy` | policy/security-review tests | Implemented | +| Destination/rebinding/redirect | `originweave-destination` | destination tests; ADR 0004 | Implemented | +| Exact direct socket/peer | `originweave-network` | real loopback + error tests; ADR 0005 | Implemented | +| TLS identity | `originweave-tls` | real rustls integration; ADR 0006 | Implemented | +| Resource budgets/mitigations | `originweave-resource` | crate tests | Implemented foundation | +| Redacted evidence/provenance | `originweave-evidence` | crate tests; ADR 0003 | Implemented foundation | +| HTTP | future/active `originweave-http` work | dedicated design/tests/PR evidence | Planned until protected merge | +| Proxy/PAC | destination foundation + future adapter | roadmap/TRD | Planned/active | +| Session/observation/action | future crates/adapters | roadmap/TRD/UML | Planned/active | +| Secret broker | future bounded service/crate | PRD/TRD | Planned/active | +| BiDi/CDP/WebMCP/MCP | adapter crates | protocol compatibility tests required | Planned | +| WARC/PROV persistence | persistence adapters | doctoring + future conformance tests | Planned | + +## 5. Requirement-to-ADR trace + +| Requirement | Governing ADR | +|---|---| +| PRD-COMP-001, PRD-COMP-003 | ADR 0001 | +| PRD-ACT-001, PRD-ACT-005, PRD-CRAWL-001, trust-source boundary | ADR 0002 | +| PRD-EVD-001, PRD-EVD-002, PRD-EVD-005 | ADR 0003 | +| PRD-NET-001, PRD-NET-002, redirect/rebinding boundary | ADR 0004 | +| PRD-NET-003 | ADR 0005 | +| PRD-NET-004 | ADR 0006 | +| Session/context/document node binding | Proposed/active decision; index only after dedicated ADR reaches protected main | +| Proxy/PAC route execution | Proposed/active decision; protected-main index updates after merge | +| HTTP semantics | Proposed/active decision; protected-main index updates after merge | +| Sensitive-data broker lifecycle | Proposed/active decision; policy/evidence slices do not equal full broker acceptance | +| Enterprise deployment/privacy | Open ADR family before production release | + +## 6. Standards-to-decision trace + +The canonical APA 7th bibliography is [`../doctoring.md`](../doctoring.md). This matrix points to the decision use; it does not duplicate the bibliography. + +| Standard / primary evidence family | OriginWeave use | +|---|---| +| WHATWG URL + Chromium canonicalizer | Browser-compatible origin identity and numeric-host rejection | +| IANA special-purpose registries / RFC 6890 / RFC 8190 / RFC 9637 | Destination classification and fail-closed public-web policy | +| RFC 9293 | Exact TCP endpoint/peer model | +| RFC 5280 / RFC 9525 / current TLS guidance | Certificate path and HTTPS service identity | +| RFC 9110 and related HTTP specifications | Redirect and bounded HTTP semantics | +| RFC 9309 | Crawler robots evidence, explicitly not access authorization | +| W3C WebDriver BiDi | Versioned browser automation adapter, not core authority | +| Chrome DevTools Protocol | Chromium-specific observation/diagnostic adapter | +| Chrome Manifest V3 documentation | Extension compatibility baseline | +| W3C PROV-O / ISO 28500 WARC | Provenance and web-capture interoperability | +| NIST AI 600-1 / web-agent prompt-injection research | Trust-class separation and model risk testing | +| WCAG 2.2 / ISO/IEC 40500:2025 | Product UI accessibility target | + +Material claims should update `docs/doctoring.md` with current primary evidence rather than relying on this summary. + +## 7. Diagram-to-requirement trace + +| Diagram | Requirements represented | +|---|---| +| UML component/bounded-context view | Product family, Chromium/Rust ownership, adapter boundaries | +| Network authority sequence | PRD-NET-001..007; TRD-INV-002 | +| Observation/action sequence | PRD-OBS, PRD-ACT, PRD-DATA, trust separation | +| Delegated-task state machine | session lifecycle, approval, resource pause, cancellation/recovery, post-condition truth | +| Deployment topology | renderer trust, orchestrator/model/store boundaries | +| Evidence authority flow | PRD-EVD; separation of proposal/policy/approval/execution/outcome | +| Conceptual ERD | durable session/action/network/sensitive/resource/provenance identity | + +## 8. Conversation-to-repository capture rule + +A **conversation-derived** decision is not binding merely because it was repeated. During maintenance, evaluate whether it affects product identity, public API, authority/security/privacy, data/evidence model, interoperability, resource behavior, lifecycle, non-goals, or release criteria. + +If material and absent from GitHub: + +1. record it as `Proposed` or `Open` in PRD/TRD/traceability; +2. create/supersede an ADR when it changes a governing architecture decision; +3. update UML/ERD when relationships or lifecycles change; +4. add standards/research to `docs/doctoring.md` when evidence is material; +5. add executable tests before calling production behavior Implemented; +6. update the protected-main ADR index only after review and merge. + +This rule intentionally prevents chat history from becoming a shadow architecture database. + +## 9. Documentation drift checks + +Repository contracts should fail when the canonical PRD/TRD/ADR index/UML/ERD/traceability files disappear or when core status/authority vocabulary is removed. More semantic checks should be added when a specific drift has caused a real defect; avoid brittle tests that duplicate prose without protecting a contract. + +## 10. Open traceability work + +- **Open:** attach concrete release profiles and quantitative benchmark thresholds after reproducible benchmark evidence exists. +- **Open:** map every future public OriginWeave Protocol operation to risk/capability/authority and conformance tests. +- **Open:** map enterprise controls to exact SOC 2/CSAP-oriented control evidence without claiming certification. +- **Open:** add data-retention and residency lifecycle diagrams when persistence/tenant adapters become concrete. +- **Open:** after active feature PRs merge, update this matrix from `Proposed/active development` to the exact protected implementation and Accepted ADRs. diff --git a/docs/uml/README.md b/docs/uml/README.md new file mode 100644 index 000000000..1d04ab00a --- /dev/null +++ b/docs/uml/README.md @@ -0,0 +1,407 @@ +# OriginWeave UML and Control-Flow Diagrams + +- **Status:** Proposed authoritative diagram pack +- **Notation:** Mermaid diagram-as-code +- **Textual authority:** [`../../ARCHITECTURE.md`](../../ARCHITECTURE.md), [`../TRD.md`](../TRD.md), and Accepted ADRs + +These diagrams visualize governing boundaries; they do not imply that every planned adapter is already shipped. Labels use `implemented`, `active`, or `planned` where implementation status matters. + +## 1. Component and bounded-context view + +```mermaid +flowchart TB + subgraph UX[User / Enterprise Experience] + human[Human browser user] + admin[Enterprise administrator] + agent[External agent / orchestrator] + end + + subgraph Product[OriginWeave Product Surfaces] + browser[OriginWeave Browser\nplanned] + runtime[OriginWeave Runtime\nplanned] + observe[OriginWeave Observe\nplanned] + capture[OriginWeave Capture\nplanned] + governor[OriginWeave Governor\nfoundation implemented] + policy[OriginWeave Policy\nfoundation implemented] + evidence[OriginWeave Evidence\nfoundation implemented] + protocol[OriginWeave Protocol / SDK\nplanned] + end + + subgraph Rust[Rust Control Plane] + core[originweave-core] + policy_crate[originweave-policy] + destination[originweave-destination] + network[originweave-network] + tls[originweave-tls] + resource[originweave-resource] + evidence_crate[originweave-evidence] + http[HTTP / proxy / session / action / observation\nplanned or active PR work] + end + + subgraph Chromium[Chromium Compatibility Kernel] + blink[Blink] + v8[V8] + viz[Skia / Viz / Dawn] + sandbox[Sandbox / Site Isolation] + extensions[Manifest V3 extensions] + end + + subgraph Adapters[External Protocol Adapters] + bidi[WebDriver BiDi\nplanned] + cdp[CDP\nplanned] + webmcp[WebMCP\nplanned / experimental upstream] + mcp[MCP\nplanned] + end + + human --> browser + admin --> browser + agent --> protocol + browser --> runtime + protocol --> runtime + runtime --> observe + runtime --> capture + runtime --> governor + runtime --> policy + runtime --> evidence + policy --> core + policy --> policy_crate + runtime --> destination --> network --> tls --> http + governor --> resource + evidence --> evidence_crate + runtime --> Adapters + Adapters --> Chromium + browser --> Chromium +``` + +## 2. Network and service-authority sequence + +```mermaid +sequenceDiagram + autonumber + participant U as User / Task Authority + participant O as Canonical Origin + participant D as Destination Policy + participant R as Route / Proxy Policy + participant N as Direct TCP Authority + participant T as TLS Identity + participant H as HTTP Semantics + participant B as Browser Adapter + participant E as Evidence + + U->>O: approve bounded target origin + O->>D: request origin-bound resolution approval + D-->>O: approved nonempty address snapshot + O->>R: select direct/proxy route under explicit policy + R-->>N: exact authorized connection target + N->>N: connect exact socket + verify peer_addr + N-->>T: verified stream + TCP evidence + T->>T: verify canonical DNS/IP identity, roots, time, ALPN + T-->>H: authenticated stream + TLS evidence + H->>H: enforce framing, bytes, integrity, MIME, redirect budgets + H-->>B: bounded exchange / redirect metadata + B->>E: bind adapter result to all independent authority evidence + Note over D,H: A green result at one layer never substitutes for the next layer. +``` + +## 3. Observation-to-action sequence + +```mermaid +sequenceDiagram + autonumber + participant Goal as Trusted User Goal + participant Session as Agent Task Session + participant Page as Untrusted Web Page + participant Observe as OriginWeave Observe + participant Model as Model / Orchestrator + participant Policy as Deterministic Policy + participant Broker as Secret Broker + participant Adapter as Browser Action Adapter + participant Evidence as Evidence Trail + + Goal->>Session: establish task purpose + capabilities + origins + Session->>Observe: request bounded observation + Page-->>Observe: tool / structured / network / AX-DOM-layout / visual data + Observe-->>Model: typed untrusted observation + node authority + Model->>Policy: propose typed action intent + Policy->>Policy: validate session, purpose, capability, origin, risk, approval + alt secret needed + Policy-->>Broker: authorize opaque handle use under exact scope + Broker-->>Adapter: trusted value fill without model disclosure + end + Policy-->>Adapter: authorized typed action + Adapter->>Page: trusted input event / navigation + Page-->>Adapter: resulting observable state + Adapter->>Adapter: verify declared post-condition + Adapter-->>Evidence: action + policy + source + post-condition evidence + Evidence-->>Model: safe outcome summary / references +``` + +## 4. Delegated-task state machine + +```mermaid +stateDiagram-v2 + [*] --> Created + Created --> Authorized: task purpose + policy accepted + Created --> Rejected: invalid authority + Authorized --> Active: isolated/attached context ready + Active --> Observing + Observing --> Planning: bounded observation complete + Planning --> AwaitingApproval: risk requires human/dual control + AwaitingApproval --> Planning: exact approval supplied + AwaitingApproval --> Cancelled: rejected / expired + Planning --> Acting: deterministic gates pass + Acting --> Verifying + Verifying --> Observing: post-condition passed, more work remains + Verifying --> Failed: post-condition absent or unsafe transition + Observing --> Paused: resource pressure / operator pause + Planning --> Paused: resource pressure / provider pause + Paused --> Active: authority and resources revalidated + Active --> Cancelled: user/operator cancellation + Observing --> Completed: goal satisfied without mutation + Verifying --> Completed: final post-condition satisfied + Failed --> Recovering: safe checkpoint/retry path exists + Recovering --> Active: exact state revalidated + Recovering --> Quarantined: ambiguous external side effect + Completed --> [*] + Cancelled --> [*] + Quarantined --> [*] +``` + +The complete durable runtime state machine is **Planned**. The important contract is that cancellation, resource pause, approval, failure, ambiguous external effects, and post-condition verification are explicit states rather than hidden boolean flags. + +## 5. Deployment and trust-boundary topology + +```mermaid +flowchart LR + subgraph ClientBoundary[Client / Human Boundary] + desktop[OriginWeave Browser\nplanned desktop distribution] + sdk[OriginWeave SDK / MCP client\nplanned] + end + + subgraph RuntimeBoundary[OriginWeave Trusted Runtime] + rt[Runtime / session authority] + pol[Policy engine] + net[Destination -> route -> TCP -> TLS -> HTTP] + sec[Secret broker] + obs[Observation / action adapters] + ev[Evidence / provenance] + gov[Resource governor] + end + + subgraph BrowserBoundary[Chromium Process Boundary] + browserproc[Browser process] + renderer[Renderer processes\nuntrusted/compromise-tolerant] + gpuproc[GPU process] + ext[MV3 extension runtime] + end + + subgraph External[External Services] + web[Web origins / APIs] + orch[contextual-orchestrator or other agent] + model[Model provider] + store[Relational / WARC / object / provenance stores\nplanned adapters] + end + + desktop --> rt + sdk --> rt + orch --> sdk + rt --> pol + rt --> net + rt --> sec + rt --> obs + rt --> ev + rt --> gov + obs --> browserproc + browserproc --> renderer + browserproc --> gpuproc + browserproc --> ext + net --> web + rt -. bounded model request .-> model + ev -. credential-free evidence .-> store + renderer -. page content is data only .-> obs +``` + +## 6. Evidence authority flow + +```mermaid +flowchart TD + source[source_resource / page / response] + observation[observation_evidence] + proposal[model_proposal\nnon-authoritative] + policy[policy_decision] + approval[approval_evidence] + network[network + TLS + HTTP evidence] + action[action_event] + post[post_condition_evidence] + value[extracted_value] + prov[provenance_record] + result[task result / audit view] + + source --> observation + observation --> proposal + proposal --> policy + approval --> policy + network --> action + policy --> action + observation --> action + action --> post + observation --> value + value --> prov + source --> prov + action --> prov + post --> prov + policy --> prov + prov --> result +``` + +A model proposal can explain *why an action was proposed* but is not mergeable with `policy_decision`, `approval_evidence`, `network` authority, or `post_condition_evidence` into one undifferentiated success status. + +## 7. Secret-fill sequence + +```mermaid +sequenceDiagram + autonumber + participant Goal as Trusted User / Enterprise Authority + participant Session as Governed Session / Task + participant Model as Model / Planner + participant Policy as Deterministic Policy + participant Broker as Secret Broker + participant Adapter as Trusted Browser Adapter + participant Page as Untrusted Page + participant Evidence as Credential-free Evidence + + Goal->>Session: authorize purpose, origin, capability, task scope + Model->>Policy: propose secret_fill(opaque_handle, target, action_intent) + Note over Model,Policy: Model never receives the raw secret. + Policy->>Policy: validate mode, purpose, capability, origin, risk, approval, exact scope + alt authority mismatch / stale approval / invalid handle scope + Policy-->>Model: deny without broker resolution + Policy-->>Evidence: denial + scope references + else policy permits broker use + Policy->>Broker: resolve opaque handle under exact authorized scope + Broker->>Broker: validate tenant/task, destination, expiry, revocation, use policy + alt broker validation fails + Broker-->>Policy: fail closed + Policy-->>Evidence: broker denial without raw value + else broker validation succeeds + Broker-->>Adapter: minimum secret value on trusted delivery path + Adapter->>Page: fill only the authorized field/action + Page-->>Adapter: resulting observable state + Adapter-->>Evidence: delivery reference + post-condition; no raw secret + end + end +``` + +Page content, model output, logs, and evidence can reference an opaque handle or redacted fingerprint but cannot request broker authority or receive the durable raw value merely by describing it. + +## 8. Read/write risk approval flow + +```mermaid +flowchart TD + intent[Typed action intent] --> classify[Classify mutability + risk] + classify --> read{Read-only and within declared capability?} + read -- yes --> readpolicy[Validate purpose, session, origin, destination, resource policy] + readpolicy -->|pass| execute_read[Execute bounded read] + readpolicy -->|deny| denied[Denied / unsupported] + read -- no --> writepolicy[Validate write capability, exact target, intent digest, risk tier] + writepolicy --> approval{Exact approval required?} + approval -- no --> execute_write[Execute typed action] + approval -- yes --> approvalcheck{Fresh in-scope approval supplied by authorized authority?} + approvalcheck -- no --> waiting[Await approval / deny on expiry or rejection] + approvalcheck -- yes --> execute_write + execute_read --> verify[Verify declared result] + execute_write --> verify + verify --> ok{Post-condition established?} + ok -- yes --> evidence[Record separate observation, policy, approval, action, post-condition evidence] + ok -- no --> quarantine[Failed or quarantined; never mark success] + page[Untrusted page content] -. cannot approve .-> approvalcheck + model[Model proposal] -. cannot approve .-> approvalcheck +``` + +A page, model, comment, status check, or other observation cannot synthesize approval. Approval is an independent authority bound to the action contract, and a valid approval does not substitute for post-condition verification. + +## 9. Resource-pressure and fallback flow + +```mermaid +flowchart TD + task[Task/session admission request] --> budget[Evaluate CPU, RAM, GPU, VRAM, network, storage and concurrency budgets] + budget --> fits{Fits bounded budget?} + fits -- no --> reject[Reject or queue before unsafe launch] + fits -- yes --> run[Run browser + optional model under governor] + run --> pressure{Resource pressure detected?} + pressure -- no --> preserve[Continue within budget] + pressure -- yes --> browserneed{Browser resources required for current observation/action verification?} + browserneed -- yes --> modeldegrade[Degrade optional model first] + modeldegrade --> reduce[Reduce model concurrency / batch] + reduce --> fallback{Policy permits CPU or remote-model fallback?} + fallback -- yes --> modelalternate[Use governed alternate model path] + fallback -- no --> modelpause[Pause or fail model-backed work] + browserneed -- no --> boundeddegrade[Apply documented bounded capture/model degradation] + modelalternate --> browserok{Browser still verifiable and inside hard limits?} + modelpause --> browserok + boundeddegrade --> browserok + browserok -- yes --> preserve + browserok -- no --> stop[Pause/fail task before state-changing action or verification loss] + preserve --> evidence[Record resource decision and resulting evidence] + stop --> evidence +``` + +The browser is not unbounded: browser correctness is prioritized over optional model acceleration, but hard host and tenant limits still fail closed. A task cannot be recorded as successfully changed when resource eviction prevents the browser from establishing its post-condition. + +## 10. Hourly product-development gate-to-model flow + +```mermaid +flowchart TD + trigger[Hourly / manual trigger on protected workflow definition] --> snapshot[Refetch exact protected main, open PRs/issues, release blockers and writer lease] + snapshot --> openpr{Open PR exists?} + openpr -- yes --> openstate[Emit open_pull_request deterministic state] + openstate --> nostart[Stop before NVIDIA_NIM_API_KEY materialization] + openpr -- no --> deterministic{Release blocker, dry-run or deterministic product/release gate?} + deterministic -- yes --> deterministic_result[Handle deterministic state without model credential] + deterministic -- no --> credential{Conditional credential gate authorized and broker healthy?} + credential -- no --> credentialdenied[credential denied or broker unavailable] + credentialdenied --> stopnosecret[stop without secret materialization] + credential -- yes --> broker[Expose NVIDIA_NIM_API_KEY only to authorized credential/broker path] + broker --> pristine[Create pristine workspace from exact HEAD] + pristine --> attempt[Run bounded model attempt] + attempt --> classify{Attempt result} + classify -- success --> seal[Seal credential-free bounded change bundle] + classify -- model_timeout --> retry{Broker healthy and remaining budget feasible?} + classify -- model_or_tool_failure --> retry + classify -- credential_broker_unavailable --> stopmodel[Stop model fallback] + retry -- yes --> pristine + retry -- no --> stopmodel + seal --> validate[Independent tests, coverage, security and secret-fingerprint validation] + validate --> validation{Validation result} + validation -- failed --> validationfailed[validation failed] + validationfailed --> failclosed[fail closed without publication] + validation -- passed --> validationpassed[validation passed] + validationpassed --> changed{Verified non-empty change?} + changed -- no --> evidence[Record deterministic no-change / product result] + changed -- yes --> publish{Publication authority available and live state unchanged?} + publish -- no --> failclosed + publish -- yes --> pr[Open/update one reviewed PR] + pr --> governance[Independent exact-head checks, review and protected branch policy] + governance --> merge[Protected merge only when all authorities pass] + merge --> acceptance[Protected-main scheduled/manual operational acceptance] +``` + +The credential decision is fail closed: `credential denied or broker unavailable` reaches `stop without secret materialization`. The validation decision is also fail closed: `validation failed` reaches `fail closed without publication`; only `validation passed` can proceed to non-empty-change and publication decisions. + +This diagram describes the governing workflow architecture and closure contract. It is not evidence that an active incident repair has merged or that protected-main acceptance has already occurred. `COPILOT_GITHUB_TOKEN`, invented PATs, raw-secret rematerialization, synthesized approval, and fail-open publication are outside the design. + +## 11. Diagram maintenance rules + +Update this pack when a protected change materially alters: + +- product/bounded-context ownership; +- authority ordering or trust boundaries; +- task/session lifecycle; +- observation hierarchy or action lifecycle; +- secret-broker delivery or approval semantics; +- resource admission, pressure, or browser/model fallback priority; +- hourly deterministic/model gate ordering or operational-closure evidence; +- deployment boundaries; +- evidence/provenance relationships. + +A feature-specific ADR may include a more detailed sequence diagram, but this pack remains the product-wide view and must not require maintainers to reconstruct the complete system from scattered ADR diagrams. diff --git a/tests/test_data_governance_documentation_contract.py b/tests/test_data_governance_documentation_contract.py new file mode 100644 index 000000000..52336a4b9 --- /dev/null +++ b/tests/test_data_governance_documentation_contract.py @@ -0,0 +1,81 @@ +"""Regression contracts for OriginWeave's purpose-bound data-governance documentation.""" + +from __future__ import annotations + +import pathlib +import unittest + +ROOT = pathlib.Path(__file__).resolve().parents[1] + + +class DataGovernanceDocumentationContractTests(unittest.TestCase): + """Keep privacy and sensitive-data authority explicit and acquisition-reviewable.""" + + def test_data_governance_is_part_of_the_authoritative_graph(self) -> None: + """The canonical index must expose data governance without chat reconstruction.""" + + governance_path = ROOT / "docs/DATA_GOVERNANCE.md" + self.assertTrue(governance_path.is_file()) + index = (ROOT / "docs/README.md").read_text(encoding="utf-8") + self.assertIn("DATA_GOVERNANCE.md", index) + self.assertIn("data-governance", index) + + def test_data_governance_rejects_both_blanket_masking_and_ambient_access(self) -> None: + """Privacy controls must preserve legitimate enterprise workflows without ambient disclosure.""" + + governance = (ROOT / "docs/DATA_GOVERNANCE.md").read_text(encoding="utf-8").casefold() + for phrase in ( + "blanket masking", + "ambient raw-value propagation", + "purpose-bound", + "field-scoped", + "just-in-time disclosure", + "opaque handle", + "trusted broker", + "model/provider/region", + "break-glass", + "retention", + "deletion", + "data residency", + ): + with self.subTest(phrase=phrase): + self.assertIn(phrase, governance) + + def test_data_governance_keeps_core_and_host_persistence_authority_separate(self) -> None: + """A conceptual ERD must not silently invent an OriginWeave production database.""" + + governance = (ROOT / "docs/DATA_GOVERNANCE.md").read_text(encoding="utf-8") + for phrase in ( + "does not claim a production application database", + "separate accepted ADR", + "backup/restore", + "two-or-more-word `snake_case`", + ): + with self.subTest(phrase=phrase): + self.assertIn(phrase, governance) + + def test_sensitive_evidence_contract_never_uses_protected_values_as_audit_metadata(self) -> None: + """Evidence may reconstruct authority without becoming another sensitive-data copy.""" + + governance = (ROOT / "docs/DATA_GOVERNANCE.md").read_text(encoding="utf-8") + for phrase in ( + "without copying the protected value", + "field identifiers and classification", + "approval or break-glass reference", + "encryption-key reference/rotation epoch without key material", + "not by itself a durable append-only audit service", + ): + with self.subTest(phrase=phrase): + self.assertIn(phrase, governance) + + def test_compliance_language_is_readiness_not_certification(self) -> None: + """Engineering documentation must not synthesize CSAP or SOC 2 certification claims.""" + + governance = (ROOT / "docs/DATA_GOVERNANCE.md").read_text(encoding="utf-8") + self.assertIn("CSAP/SOC 2 readiness", governance) + self.assertIn("does not claim certification", governance) + self.assertIn("independent certification/examination result", governance) + + +if __name__ == "__main__": + unittest.main() diff --git a/tests/test_product_data_model_contract.py b/tests/test_product_data_model_contract.py new file mode 100644 index 000000000..968ad1c59 --- /dev/null +++ b/tests/test_product_data_model_contract.py @@ -0,0 +1,62 @@ +"""Regression contracts for the conceptual OriginWeave product data/evidence model.""" + +from __future__ import annotations + +import pathlib +import unittest + +ROOT = pathlib.Path(__file__).resolve().parents[1] + + +class ProductDataModelContractTests(unittest.TestCase): + """Keep durable identities separate across session, source, action, and evidence domains.""" + + def test_conceptual_erd_covers_required_product_entities(self) -> None: + erd = (ROOT / "docs/erd/README.md").read_text(encoding="utf-8") + for entity in ( + "tenant_record", + "agent_session", + "browser_profile", + "page_snapshot", + "semantic_node", + "network_exchange", + "content_record", + "extraction_schema", + "extracted_value", + "action_event", + "policy_decision", + "approval_evidence", + "provenance_record", + "download_artifact", + "task_checkpoint", + "resource_budget", + "secret_handle", + "extension_grant", + ): + with self.subTest(entity=entity): + self.assertIn(entity, erd) + + def test_conceptual_erd_does_not_claim_unimplemented_persistence(self) -> None: + erd = (ROOT / "docs/erd/README.md").read_text(encoding="utf-8") + for phrase in ( + "Conceptual unless", + "does not yet implement every entity as a relational table", + "Planned durable record", + "Adapter-owned representation", + ): + with self.subTest(phrase=phrase): + self.assertIn(phrase, erd) + + def test_extraction_schema_is_distinct_from_values_and_source_content(self) -> None: + erd = (ROOT / "docs/erd/README.md").read_text(encoding="utf-8") + for relationship in ( + "extraction_schema ||--o{ extracted_value", + "content_record ||--o{ extracted_value", + "source_resource ||--o{ content_record", + ): + with self.subTest(relationship=relationship): + self.assertIn(relationship, erd) + + +if __name__ == "__main__": + unittest.main() diff --git a/tests/test_product_documentation_contract.py b/tests/test_product_documentation_contract.py new file mode 100644 index 000000000..66a67d52f --- /dev/null +++ b/tests/test_product_documentation_contract.py @@ -0,0 +1,134 @@ +"""Regression contracts for OriginWeave's authoritative product documentation graph.""" + +from __future__ import annotations + +import pathlib +import unittest + +ROOT = pathlib.Path(__file__).resolve().parents[1] + + +class ProductDocumentationContractTests(unittest.TestCase): + """Keep product requirements, technical design, diagrams, and traceability discoverable.""" + + def test_authoritative_product_documentation_graph_exists(self) -> None: + """Major product decisions must not require reconstructing chat or PR history.""" + required_paths = { + "docs/PRD.md", "docs/TRD.md", "docs/adr/README.md", "docs/uml/README.md", + "docs/erd/README.md", "docs/traceability/README.md", "docs/THREAT_MODEL.md", + "docs/TEST_STRATEGY.md", "docs/OPERABILITY.md", "docs/API_CONTRACT.md", + "docs/RELEASE_AND_ROLLBACK.md", + } + missing = sorted(path for path in required_paths if not (ROOT / path).is_file()) + self.assertEqual(missing, []) + + def test_root_architecture_links_the_authoritative_product_graph(self) -> None: + """Architecture readers must be able to reach requirements, decisions, diagrams, and data.""" + architecture = (ROOT / "ARCHITECTURE.md").read_text(encoding="utf-8") + for link in ("docs/PRD.md", "docs/TRD.md", "docs/adr/README.md", "docs/uml/README.md", "docs/erd/README.md", "docs/traceability/README.md"): + with self.subTest(link=link): self.assertIn(link, architecture) + + def test_security_policy_links_the_product_threat_model(self) -> None: + """Vulnerability reporters and operators must be able to find modeled trust boundaries.""" + self.assertIn("docs/THREAT_MODEL.md", (ROOT / "SECURITY.md").read_text(encoding="utf-8")) + + def test_agent_contract_is_work_conserving_instead_of_one_action_per_run(self) -> None: + """Finishing one bounded slice must return maintenance to the live queue.""" + contract = (ROOT / "AGENTS.md").read_text(encoding="utf-8") + for phrase in ("A completed action is an intermediate state", "one write-active slice at a time", "Mandatory exit sweep", "termination is prohibited", "blocks only that item"): + with self.subTest(phrase=phrase): self.assertIn(phrase, contract) + + def test_prd_covers_product_family_modes_and_buyer_acceptance(self) -> None: + """The PRD must describe the actual product family rather than one kernel slice.""" + prd = (ROOT / "docs/PRD.md").read_text(encoding="utf-8") + for phrase in ("Browse. Act. Prove.", "Human Mode", "Assist Mode", "Agent Task Mode", "Crawler Mode", "OriginWeave Browser", "OriginWeave Runtime", "OriginWeave Observe", "OriginWeave Capture", "OriginWeave Governor", "OriginWeave Policy", "OriginWeave Evidence", "OriginWeave Protocol", "Non-goals", "Buyer-visible acceptance"): + with self.subTest(phrase=phrase): self.assertIn(phrase, prd) + + def test_trd_distinguishes_shipped_architecture_from_future_work(self) -> None: + """Technical documentation must not silently describe planned work as shipped.""" + trd = (ROOT / "docs/TRD.md").read_text(encoding="utf-8") + for phrase in ("Implemented", "Accepted architecture", "Planned", "logical origin", "resolved destination", "TCP peer", "TLS service identity", "WebDriver BiDi", "Chrome DevTools Protocol", "WebMCP", "Model Context Protocol", "NVIDIA_NIM_API_KEY", "COPILOT_GITHUB_TOKEN"): + with self.subTest(phrase=phrase): self.assertIn(phrase, trd) + + def test_target_architecture_adr_set_is_detailed(self) -> None: + """Product direction must be reconstructable from durable, reviewable decisions.""" + required_adrs = { + "docs/adr/0001-chromium-compatibility-kernel.md": ("Chromium", "browser-engine rewrite"), + "docs/adr/0100-rust-control-plane-boundary.md": ("Rust control plane", "Chromium compatibility kernel"), + "docs/adr/0101-isolated-execution-profile-modes.md": ("Human", "Assist", "Agent Task", "Crawler"), + "docs/adr/0102-typed-actions-and-arbitrary-js.md": ("typed action", "arbitrary JavaScript"), + "docs/adr/0103-semantic-observation-and-stale-node-identity.md": ("WebMCP", "accessibility", "document epoch", "stale"), + "docs/adr/0104-prompt-injection-and-secret-authority.md": ("prompt injection", "opaque", "secret"), + "docs/adr/0105-resource-governor-priority.md": ("resource governor", "GPU", "browser", "model"), + "docs/adr/0106-provenance-evidence-model.md": ("WARC", "PROV", "evidence"), + "docs/adr/0107-browser-protocol-adapter-strategy.md": ("WebDriver BiDi", "Chrome DevTools Protocol", "WebMCP", "Model Context Protocol"), + "docs/adr/0108-crawler-policy.md": ("robots", "rate", "CAPTCHA"), + "docs/adr/0109-hourly-automation-operational-closure.md": ("NVIDIA_NIM_API_KEY", "protected-main", "open_pull_request"), + } + sections = ("## Context", "## Options considered", "## Decision", "## Consequences", "## Failure and degraded behavior", "## Security / privacy / governance impact", "## Tests and acceptance evidence", "## Migration and rollback", "## Supersession / reversal conditions") + fields = ("- Status:", "- Date:", "- Supersedes:", "- Superseded by:") + for path, phrases in required_adrs.items(): + with self.subTest(path=path): + text = (ROOT / path).read_text(encoding="utf-8") + for field in fields: self.assertIn(field, text) + for section in sections: self.assertIn(section, text) + for phrase in phrases: self.assertIn(phrase, text) + + def test_stale_node_adr_defines_action_linearization_race(self) -> None: + """A mutation between handle validation and dispatch must never produce a stale side effect.""" + adr = (ROOT / "docs/adr/0103-semantic-observation-and-stale-node-identity.md").read_text(encoding="utf-8") + for phrase in ("action linearization point", "side effect", "competing mutation", "re-observation"): + with self.subTest(phrase=phrase): self.assertIn(phrase, adr) + + def test_hourly_automation_adr_requires_exit_sweep(self) -> None: + """Automation closure must re-sweep all actionable lanes instead of stopping after one result.""" + adr = (ROOT / "docs/adr/0109-hourly-automation-operational-closure.md").read_text(encoding="utf-8") + for phrase in ("mandatory exit sweep", "open OriginWeave PRs and issues", "release state", "documentation", "product gaps", "safe actionable work remains"): + with self.subTest(phrase=phrase): self.assertIn(phrase, adr) + + def test_uml_and_erd_are_diagram_as_code(self) -> None: + """Architecture flows and the conceptual domain model must be reviewable in Git.""" + uml = (ROOT / "docs/uml/README.md").read_text(encoding="utf-8") + erd = (ROOT / "docs/erd/README.md").read_text(encoding="utf-8") + self.assertGreaterEqual(uml.count("```mermaid"), 8); self.assertIn("sequenceDiagram", uml); self.assertIn("stateDiagram-v2", uml) + for heading in ("Secret-fill sequence", "Read/write risk approval flow", "Resource-pressure and fallback flow", "Hourly product-development gate-to-model flow"): + with self.subTest(heading=heading): self.assertIn(heading, uml) + self.assertIn("erDiagram", erd) + for entity in ("agent_session", "browser_profile", "page_snapshot", "semantic_node", "action_event", "policy_decision", "provenance_record", "resource_budget"): + with self.subTest(entity=entity): self.assertIn(entity, erd) + + def test_hourly_uml_fails_closed_before_secret_or_publication(self) -> None: + """Denied credentials and failed validation must terminate before secret use or publication.""" + uml = (ROOT / "docs/uml/README.md").read_text(encoding="utf-8") + for phrase in ("credential denied or broker unavailable", "stop without secret materialization", "validation failed", "fail closed without publication", "validation passed"): + with self.subTest(phrase=phrase): self.assertIn(phrase, uml) + + def test_operational_documents_preserve_fail_closed_product_boundaries(self) -> None: + """Security, operations, APIs, tests, and rollback must agree on core authority boundaries.""" + documents = { + "docs/THREAT_MODEL.md": ("renderer compromise", "prompt injection", "confused deputy", "cross-tenant"), + "docs/TEST_STRATEGY.md": ("true production boundary", "100%", "hostile", "protected-main"), + "docs/OPERABILITY.md": ("SLI", "SLO", "quarantine", "break-glass"), + "docs/API_CONTRACT.md": ("OriginWeave Protocol", "idempotency", "post-condition", "opaque"), + "docs/RELEASE_AND_ROLLBACK.md": ("SBOM", "provenance", "rollback", "protected main"), + } + for path, phrases in documents.items(): + text = (ROOT / path).read_text(encoding="utf-8") + for phrase in phrases: + with self.subTest(path=path, phrase=phrase): self.assertIn(phrase, text) + + def test_release_contract_never_bypasses_evidence_or_reproducibility(self) -> None: + """Emergency release handling must preserve exact-head gates and reproducible artifacts.""" + release = (ROOT / "docs/RELEASE_AND_ROLLBACK.md").read_text(encoding="utf-8") + for phrase in ("Emergency releases do not bypass required gates", "current-head checks", "complete coverage", "branch protection", "reproducible artifact", "nondeterministic signing"): + with self.subTest(phrase=phrase): self.assertIn(phrase, release) + self.assertNotIn("residual unrun evidence", release) + + def test_traceability_labels_conversation_derived_future_work(self) -> None: + """Conversation decisions must preserve implementation status instead of becoming claims.""" + traceability = (ROOT / "docs/traceability/README.md").read_text(encoding="utf-8") + for phrase in ("Implemented", "Accepted architecture", "Proposed", "Open", "conversation-derived", "docs/doctoring.md"): + with self.subTest(phrase=phrase): self.assertIn(phrase, traceability) + + +if __name__ == "__main__": unittest.main() diff --git a/tests/test_review_governance_documentation_consistency.py b/tests/test_review_governance_documentation_consistency.py new file mode 100644 index 000000000..1e2c67f5b --- /dev/null +++ b/tests/test_review_governance_documentation_consistency.py @@ -0,0 +1,62 @@ +"""Keep contributor guidance aligned with the satisfiable review-governance policy.""" + +from __future__ import annotations + +import pathlib +import unittest + +ROOT = pathlib.Path(__file__).resolve().parents[1] +AGENTS = ROOT / "AGENTS.md" +QUALITY_GATES = ROOT / "docs" / "quality-gates.md" + + +class ReviewGovernanceDocumentationConsistencyTests(unittest.TestCase): + """Prevent the agent contract from recreating an impossible approval gate.""" + + @classmethod + def setUpClass(cls) -> None: + cls.agents = AGENTS.read_text(encoding="utf-8").lower() + cls.quality_gates = QUALITY_GATES.read_text(encoding="utf-8").lower() + + def test_agent_contract_references_current_satisfiable_review_governance(self) -> None: + """Contributor guidance must preserve the same conditional approval semantics.""" + + for phrase in ( + "current github rules", + "on hold", + "solo-maintainer", + "fewer than two eligible", + "re-enabled", + ): + with self.subTest(phrase=phrase): + self.assertIn(phrase, self.agents) + self.assertIn(phrase, self.quality_gates) + + def test_agent_contract_does_not_recreate_unconditional_independent_approval(self) -> None: + """The old unconditional wording contradicts the merged governance rule.""" + + self.assertNotIn( + "do not bypass required checks, independent approval, or branch protection", + self.agents, + ) + self.assertNotIn( + "a qualifying approval is a formal `approved` review", + self.agents, + ) + + def test_technical_gates_remain_mandatory(self) -> None: + """Governance realism must not weaken deterministic product evidence.""" + + for phrase in ( + "required checks", + "branch protection", + "100%", + "rustdoc", + "review", + ): + with self.subTest(phrase=phrase): + self.assertIn(phrase, self.agents) + + +if __name__ == "__main__": + unittest.main()