diff --git a/docs/plans/GO_TO_MARKET_STRATEGY.md b/docs/plans/GO_TO_MARKET_STRATEGY.md new file mode 100644 index 0000000..4ad8124 --- /dev/null +++ b/docs/plans/GO_TO_MARKET_STRATEGY.md @@ -0,0 +1,613 @@ +# Auths: Product and Go-to-Market Strategy + +## Purpose + +This document is the operating brief for turning Auths from a strong protocol +and proof kernel into an open-core, venture-scale product. + +It is written so that another engineering agent can execute against it. It +separates decisions from hypotheses, defines the first product wedge, and +names the evidence required before expanding the product or committing to a +commercial model. + +Auths is prelaunch and pre-audit. This strategy must not describe planned +features as shipped, formal models as full-system proofs, or market hypotheses +as customer facts. + +## The ambition + +Auths should become the standard way to attach bounded, delegable authority to +software actions. + +The protocol remains open and useful without an Auths-operated service. A +company can be built around the operational products that make the protocol +easy to adopt, govern, observe, and integrate at scale. Hosted and on-premises +offerings are both part of the long-term opportunity, but neither may become a +runtime dependency of the open verifier. + +The first market is not “all authorization.” It is developers building AI +agents—especially agent-framework builders and teams building internal +agents—who need those agents to take real actions without giving them ambient, +unbounded credentials. + +The entry point is a polished SDK. Not a CLI. + +## The problem + +Authentication answers a useful question: + +> Who or what is presenting this credential? + +It does not, by itself, answer the question an executing system needs: + +> Was this actor given authority for this exact action, under these exact +> constraints, through a valid chain of delegation? + +Agents make that gap more visible. An agent may be authenticated, connected to +an MCP server, and holding a valid API credential while still having far more +authority than its current task requires. Conventional mitigations often put +the safety boundary in prompts, application conditionals, a remote policy +service, or a broadly scoped bearer token. + +Auths makes authority an explicit object that can be narrowed, carried with an +action, and verified locally before a side effect occurs. + +This is not an argument that identity systems, OAuth, API gateways, or cloud +IAM are badly designed. They solve important problems within a long and +complicated legacy. Auths addresses a different layer: proof that a particular +action falls within explicitly delegated authority. + +## Product doctrine + +These are product constraints, not optional positioning. + +### 1. Authority is distinct from identity + +Auths may use many ways to establish control of a principal: raw keys, +`did:key`, WebAuthn, KERI, SPIFFE, hardware-attested keys, or future methods. +No single identity method owns the protocol. + +Identity establishes who controls a verification method. Authority establishes +what that principal may do. Product APIs, storage types, and user-facing +language must preserve this distinction. + +### 2. Authority travels with the action + +An action is accompanied by the proof material needed to evaluate its +authority. Any policy document that accompanies the action is not trusted +merely because it is present. Its identity or digest must be committed by a +signed grant or locally trusted context, and the verifier must confirm that the +received policy is exactly the committed policy. + +### 3. Verification works locally + +Core verification must not require an Auths-hosted service, network round trip, +or account. Headless and on-premises deployments are first-class. + +Hosted products may distribute configuration, manage organizations, retain +receipts, and improve operations. They must not turn the open protocol into a +thin client for a mandatory control plane. + +### 4. Delegation only narrows + +A parent can give a child less authority, never more. The child cannot expand +permissions, resources, duration, audience, budgets, or remaining delegation +depth. + +A process restart does not reset authority. An agent that retries an +out-of-scope action remains outside its grant and receives the same terminal +denial. + +### 5. Human supervision is configurable inside the boundary + +Some users want autonomous agents that can operate freely within a grant. +Regulated teams may require approval for every consequential action. Auths +must support both without confusing supervision with authority. + +Approval policy determines when a human must sign off on an otherwise +authorized action. It cannot enlarge the agent's underlying authority. + +### 6. Profiles remain vertically bounded + +An MCP tool call, an HTTP request, a Stripe operation, and a database mutation +have different action semantics, credentials, gateways, and receipts. Shared +protocol machinery must not collapse them into a generic operation-tag +executor. + +New profiles should be implemented vertically. A shared abstraction is earned +only after multiple completed profiles demonstrate the same invariant and +lifecycle. + +### 7. Claims must match evidence + +Lean, Charon, Aeneas, Kani, conformance corpora, fuzzing, unit tests, and +integration tests provide different kinds of evidence. They strengthen the +product together; none justifies claiming that the entire system is formally +verified or free of security defects. + +The shipped Rust path, generated formal artifacts, fixtures, independent +implementations, and CI gates must remain connected so that semantic drift is +observable. + +## The first product + +The first product is a TypeScript SDK backed by the Rust Auths kernel. + +It should let a developer attach an agent to Auths, give that agent bounded +authority, wrap an MCP tool surface, delegate a narrower grant to a child, and +receive an actionable authorization result before execution. + +“Attach an agent to Auths” is the activation moment. It should be achievable +without first operating an Auths service or learning the wire format. + +```mermaid +flowchart LR + APP["Agent application"] --> ADAPTER["MCP runtime adapter"] + ADAPTER --> SDK["Auths TypeScript SDK"] + SDK --> KERNEL["Rust verification kernel"] + SDK --> AUTHOR["Grant and action authoring"] + AUTHOR --> SIGNER["Custody signer"] + SDK --> APPROVAL["Approval provider"] + KERNEL --> GATEWAY["MCP-specific closed gateway"] + GATEWAY --> TOOL["Authorized tool implementation"] + KERNEL --> DENY["Terminal denial"] +``` + +The TypeScript layer should be polished and idiomatic rather than exposing the +Rust ABI directly. Rust remains the semantic core. Additional SDKs are added +only after the first TypeScript integration demonstrates which concepts +developers actually need. + +An illustrative API—not a frozen interface—might look like: + +```ts +const securedAgent = await auths.attachAgent({ + agent, + runtime: mcp(server), + authority: signedGrant, + approval: { + mode: "risk-based", + provider: macOSTouchId(), + }, + identity: { + lifecycle: "durable", + custody: secureEnclave(), + }, +}); +``` + +The SDK should expose a small number of comprehensible concepts: + +- a principal and signer; +- a bounded grant; +- parent-to-child delegation; +- an exact action; +- an approval policy; +- an authorization decision; +- an execution receipt; +- an MCP-specific protected tool boundary. + +The SDK must not make developers assemble CBOR, digest inputs, trusted context, +or registry commitments by hand for the normal path. Those details remain +inspectable and testable. + +## Approval and key custody + +Approval and custody are ports, not identity methods. + +The SDK should define platform-neutral interfaces for: + +- approving a grant or action; +- creating or loading a signer; +- signing without exporting private key material; +- reporting whether the signer is hardware-backed; +- representing cancellation, unavailable hardware, and failed user presence. + +The first reference desktop integration should target macOS: + +- a durable parent-agent key protected by the Secure Enclave where available; +- Touch ID or device authentication as user-presence approval; +- Keychain-backed or passphrase-protected software fallback; +- no private-key extraction from the Secure Enclave. + +Touch ID is not the user's identity and a fingerprint does not become key +material. Touch ID authorizes the operating system to use a protected signing +key. + +The default identity lifecycle should be: + +- durable, hardware-backed identity for a named parent agent when supported; +- short-lived or ephemeral identity for a child or task-specific agent; +- configurable alternatives for headless servers, CI, containers, HSMs, and + other operating systems. + +Approval modes should include: + +| Mode | Intended use | Behavior | +| --- | --- | --- | +| Grant-only | Hobbyists and trusted local automation | Human approves issuance; actions inside the grant proceed autonomously | +| Risk-based | General application use | Configured action classes require approval | +| Every-action | Regulated or high-consequence workflows | Every executable action requires fresh approval | +| Custom | Organization-specific controls | The host supplies a policy decision through the approval port | + +All four modes operate inside the same cryptographic authority boundary. + +## The flagship demonstration + +Delegation is the central demonstration because it shows what Auths adds beyond +agent authentication or a conventional tool credential. + +The first demo should use an MCP tool that performs a constrained HTTP API +operation: + +1. A human creates or loads a durable parent-agent signer. +2. The human approves a bounded grant using Touch ID or a configured fallback. +3. The parent delegates a smaller, short-lived grant to a child agent. +4. The child calls an allowed MCP tool to read or update one specific resource. +5. The request carries the exact-action proof and committed policy material. +6. The MCP profile verifies the proof locally before the HTTP side effect. +7. The closed gateway executes the authorized request and emits a receipt. +8. The child attempts a delete or a request against a different resource. +9. Verification returns a terminal denial and the tool is not called. +10. Repeating or restarting the agent does not change the outcome. + +```mermaid +sequenceDiagram + autonumber + actor Human + participant Parent as Parent agent + participant Child as Child agent + participant SDK as Auths SDK + participant MCP as Protected MCP tool + participant API as HTTP API + + Human->>SDK: Approve bounded parent grant + SDK->>Parent: Durable signed authority + Parent->>Child: Delegate narrower short-lived authority + Child->>SDK: Request permitted resource update + SDK->>MCP: Exact action and proof + MCP->>MCP: Verify locally + MCP->>API: Execute authorized update + API-->>MCP: Result + MCP-->>Child: Result and execution receipt + Child->>SDK: Request forbidden delete + SDK-->>Child: Terminal denial + Note over MCP,API: No forbidden side effect occurs +``` + +The demo is complete only when a developer can inspect: + +- the root authority; +- every delegation edge and attenuation; +- the exact action commitment; +- the approval event; +- the local verdict; +- whether execution occurred; +- the resulting receipt; +- the stable reason for denial. + +The demo should work entirely on a laptop. A hosted account may later improve +sharing and observability, but cannot be required. + +## Initial customer and distribution wedge + +### Primary users + +The initial users are: + +1. maintainers of AI-agent frameworks and agent runtimes; +2. platform teams building internal agents that call MCP tools or HTTP APIs. + +Framework builders provide distribution. Internal-agent teams provide +high-value operational feedback. Both experience the same core problem: +connecting an agent to tools is easier than expressing and enforcing exactly +what the agent may do. + +### Initial message + +The first message should be concrete: + +> Attach an agent to Auths. Give it bounded authority, let it delegate less to +> child agents, and verify every real action before execution. + +Supporting messages: + +- authority, not just identity; +- local verification without a mandatory service; +- exact-action proofs rather than ambient permission; +- configurable human supervision; +- terminal denial that survives retries and restarts; +- inspectable delegation and execution receipts. + +Avoid leading with formal methods, decentralized identity, crypto-agility, or +an exhaustive list of domains. They are important foundations, not the +developer's first job to be done. + +### Distribution order + +1. Publish the flagship MCP delegation demo. +2. Recruit a small number of framework maintainers and internal-agent teams as + design partners. +3. Integrate the SDK into real agent applications with them. +4. Turn repeated integration work into stable TypeScript APIs and MCP helpers. +5. Publish reusable examples, adversarial fixtures, and conformance guidance. +6. Add framework-specific adapters only when actual integrations justify them. +7. Use observed operational pain to decide whether a CLI, visual inspector, + hosted service, or on-premises control plane should be built. + +There is no initial CLI workstream. CLI requirements should be discovered from +the SDK and demo work. A CLI may later become useful for inspection, policy +authoring, development fixtures, or operations, but none of those uses is +assumed yet. + +## Open-core boundary + +The current direction is: + +### Open + +- protocol specification and canonical encodings; +- verifier and formal models; +- core Rust implementation; +- TypeScript SDK needed to create and verify proofs locally; +- authoring libraries and signer interfaces; +- MCP profile and reference integration; +- fixtures, conformance suites, and adversarial examples; +- local approval and custody interfaces; +- enough tooling to build and operate Auths without an Auths-hosted service. + +### Potential commercial products + +- hosted organization and trust management; +- on-premises enterprise control plane; +- policy distribution and lifecycle operations; +- fleet-wide agent and grant inventory; +- durable receipt retention, search, and export; +- enterprise approval workflows; +- managed integrations with existing identity, KMS, HSM, SIEM, and workflow + systems; +- compliance-oriented reporting and governance; +- support, deployment assistance, and assurance packages. + +This boundary is a hypothesis. The company should charge for operational +coordination, governance, integration, and service—not for weakening the +standalone open protocol or placing an artificial toll on local verification. + +Pricing, packaging, and the first economic buyer are deliberately unresolved. +They require evidence from design partners. + +## What not to build yet + +Do not build these merely because they appear plausible: + +- a general-purpose CLI; +- a hosted verification dependency; +- a broad identity platform; +- a universal policy language; +- connectors for every identity provider and cloud; +- wrappers for every agent framework; +- generic profile dispatch driven by operation tags; +- a large visual control plane; +- compliance claims or predesigned compliance packages; +- speculative pricing tiers. + +Build a candidate only after the SDK work exposes a repeated problem, a design +partner confirms its value, and its ownership boundary is clear. + +## Execution program + +The tracked +[Post-Milestone 6 Productization and Release Plan](../target-state/POST_MILESTONE_6_PRODUCTIZATION_AND_RELEASE_PLAN.md) +governs technical order. The specifications below are phase-aligned workstreams, +not a competing Stage 1–5 implementation sequence. + +```text +Phase 7 RC -> Phase 8 exact claim -> Phase 9 independent review + | + v + Phase 10 SDK + local MCP preview + | + v + Phase 11 runtime + deployable custody + | + v + Phase 12 conformance -> Phase 13 flagship + | + v + Phases 14–15 workbench + public v1 + +Commercial discovery: =========================================> +Partner recruitment: =====> +Restricted integrations: =========> +Customer-operated pilots: ===========> +``` + +### Phases 7–8: reproducible candidate and exact claim + +[Specification: AP-SPEC-032, Reproducible release candidate and exact +assurance claim](../specs/0032-reproducible-release-candidate-and-exact-assurance-claim.md) + +Freeze semantic identities, prepare reproducible and attestable artifacts, +promote one immutable RC without rebuilding, and bind every public assurance +claim to its exact subjects, evidence, assumptions, and exclusions. + +### Phase 9: independent review and remediation + +[Specification: AP-SPEC-033, Independent review and remediation +gate](../specs/0033-independent-review-and-remediation-gate.md) + +Submit the fixed RC and claim bundle to formal-methods, Rust/protocol-security, +and stateful-execution reviewers. Every finding receives an owner, affected +claim, regression obligation, remediation revision, and independent retest. +No unresolved critical finding may pass the gate. + +### Phase 10: TypeScript and MCP developer preview + +- [AP-SPEC-027: TypeScript SDK developer + preview](../specs/0027-product-grade-typescript-sdk.md) +- [AP-SPEC-028: MCP delegation reference + application](../specs/0028-mcp-delegation-reference-application.md) + +The SDK is the first developer product, but its Phase 10 publication is an +explicit preview rather than GA. The MCP vertical is local, synthetic, +sandboxed, or demonstrably reversible and is not the Phase 13 production +flagship. + +### Phases 10–11: approval and custody + +[Specification: AP-SPEC-029, Human approval and platform +custody](../specs/0029-human-approval-and-custody.md) + +Phase 10 defines provider-neutral contracts, committed supervision policy, +records, and deterministic fake providers. Phase 11 owns native helpers, +Secure Enclave, software and headless custody, packaging, recovery, and scoped +security assessment. Required and executed approval-policy commitments must +match before prompting, signing, credential acquisition, or provider I/O. + +### Phases 9–13: design-partner program + +[Specification: AP-SPEC-030, Design-partner integration +program](../specs/0030-design-partner-integrations.md) + +Recruit three to five partners during Phase 9. Restrict early effects to the +review-preview boundary. Begin consequential customer-operated pilots only +after the applicable Phase 11 gates, and require at least two non-core +maintainers plus reviewed flagship evidence before program closure. + +### Phase 7 onward: commercial discovery + +[Specification: AP-SPEC-031, Commercial discovery and product +selection](../specs/0031-commercial-discovery.md) + +Problem, buyer, workflow, deployment, procurement, and willingness-to-pay +discovery begins alongside Phase 7. Product selection waits for repeated +integration evidence, a credible buyer and pilot path, an approved commercial +boundary, and willingness-to-pay evidence. No ARR target belongs in the +engineering plan before this discovery. + +### Later technical gates + +Phase 11 production runtime, Phase 12 conformance, Phase 13 flagship operation, +Phase 14 workbench, and Phase 15 public-v1 release remain governed by the +tracked target-state plan and require their own execution-ready plans before +implementation. These specifications do not collapse or bypass those gates. + +## Metrics + +Early metrics should measure product truth rather than vanity. + +### Activation + +- time from installing the SDK to the first authorized tool call; +- percentage of developers who complete parent-to-child delegation; +- percentage who successfully diagnose the intentional denied call; +- number of concepts or manual artifacts required for the first integration. + +### Product quality + +- forbidden-side-effect tests passing across every protected gateway; +- conformance agreement across supported implementations; +- semantic or generated-artifact drift caught by CI; +- stability and usefulness of denial codes; +- percentage of examples reproducible from a clean checkout; +- number of security-critical escape hatches in the default API. + +### Adoption + +- externally maintained SDK integrations; +- active agent applications verifying exact actions; +- design partners using Auths without direct implementation support; +- repeat use across more than one tool or agent workflow. + +### Commercial learning + +- organizations requesting shared governance or operations; +- hosted versus on-premises preference; +- repeated integration categories; +- buyer, budget, and procurement evidence; +- willingness to pay for a specific operational outcome. + +GitHub stars, downloads, and social reach may help distribution, but they are +not substitutes for these measures. + +## Strategic risks + +| Risk | Consequence | Response | +| --- | --- | --- | +| SDK exposes protocol complexity | Developers abandon the integration | Design around the attach/delegate/protect flow and test with external users | +| “Policy travels” becomes attacker-selected policy | Apparent authorization without trusted authority | Commit the policy identity or digest in signed authority or trusted context | +| Human approval becomes mandatory babysitting | Autonomous use cases become impractical | Keep approval configurable inside a fixed authority boundary | +| Biometrics become confused with identity | Platform coupling and misleading security claims | Treat user presence, custody, and identity as separate ports | +| MCP code leaks into the shared kernel | New domains destabilize existing ones | Preserve profile-specific vertical ownership and closed gateways | +| Formal-method language overclaims assurance | Loss of trust | State exactly what is modeled, translated, checked, and outside scope | +| Hosted product becomes required | Open-core credibility collapses | Maintain fully local, headless, and on-premises operation | +| Product expands before the wedge works | Many demos but no adoption loop | Gate expansion on design-partner evidence | +| A denied agent succeeds through retries | Authority is not actually bounded | Make denial deterministic for unchanged trusted inputs and test restart behavior | + +## Durable decisions and open questions + +### Decided + +- Build an open protocol and a venture-scale company around tools and + operations for the open core. +- Start with AI-agent framework builders and teams building internal agents. +- Lead with an SDK, not a CLI. +- Use Rust for the core and TypeScript for the first polished developer SDK. +- Make MCP the first runtime adapter and delegation the flagship demonstration. +- Support fully local, headless, hosted, and on-premises deployment models. +- Keep identity methods, approval, custody, networking, and profiles agnostic. +- Use durable parent identities and short-lived or ephemeral child identities + by default. +- Support configurable human-approval modes. +- Make out-of-authority results terminal for unchanged inputs. +- Require policies traveling with actions to be cryptographically committed. + +### Open and intentionally unresolved + +- the first economic buyer; +- the first paid product; +- packaging and pricing; +- which hosted and on-premises capabilities customers value first; +- which agent frameworks deserve dedicated adapters; +- whether recurring SDK workflows eventually justify a CLI; +- the order of platforms after the macOS reference provider; +- the long-term identity representation used by default. + +These questions should be answered by product evidence, not filled in for the +sake of a complete-looking roadmap. + +## Instructions for the executing agent + +When using this document to plan or implement work: + +1. Inspect the current repository and classify every proposed capability as + shipped, partial, or absent. +2. Preserve the kernel's offline, effect-free boundary. +3. Read the profile and domain abstraction boundary plan before modifying + application architecture. +4. Implement one vertical slice at a time. +5. Do not introduce a CLI workstream. +6. Do not add hosted dependencies to the local verification path. +7. Implement custody from this repository's platform-neutral contracts without + importing identity-method semantics into approval or key storage. +8. Test forbidden side effects, not merely denial return values. +9. Keep policy commitments, executed configuration, and received artifacts + exact and reviewable. +10. Update claims and plans only when evidence changes. +11. Stop at each phase gate and record what was learned before widening + scope. + +The immediate execution program is AP-SPEC-032: record its owner decisions, +produce the reproducible release candidate, and publish the exact claim bundle. +AP-SPEC-033 independent review follows. AP-SPEC-027 and AP-SPEC-028 remain +blocked until that review gate permits the explicitly labeled Phase 10 +developer preview. + +## Related architecture + +- [Post-Milestone 6 Productization and Release Plan](../target-state/POST_MILESTONE_6_PRODUCTIZATION_AND_RELEASE_PLAN.md) +- [Post-Milestone-6 Technical and Go-to-Market Alignment](POST_MILESTONE_6_TECHNICAL_AND_GO_TO_MARKET_ALIGNMENT.md) +- [Profile and Domain Abstraction Boundary Plan](../target-state/PROFILE_AND_DOMAIN_ABSTRACTION_BOUNDARY_PLAN.md) +- [Greenfield Foundation](../target-state/AUTHS_PROOF_GREENFIELD_FOUNDATION.md) +- [Target Workspace Topology](../adr/0009-target-workspace-topology.md) +- [Production Authority Kernel with Aeneas](../adr/0011-rich-authority-rust-lean-link.md) diff --git a/docs/plans/PHASE_7_RELEASE_OWNER_DECISIONS.md b/docs/plans/PHASE_7_RELEASE_OWNER_DECISIONS.md new file mode 100644 index 0000000..6fb0710 --- /dev/null +++ b/docs/plans/PHASE_7_RELEASE_OWNER_DECISIONS.md @@ -0,0 +1,75 @@ +# Phase 7 release owner decision register + +## Status + +Awaiting owner decisions. This document is a decision packet, not an approval +record. An unresolved row MUST NOT be interpreted as acceptance of its +recommended default. + +## Governing specification + +[AP-SPEC-032](../specs/0032-reproducible-release-candidate-and-exact-assurance-claim.md) +requires these decisions before Phase 7 release implementation begins. + +The read-only +[Phase 7 release readiness audit](PHASE_7_RELEASE_READINESS_AUDIT.md) maps each +decision to the current repository and the implementation it blocks. + +The executing agent may maintain specifications, inspect the repository, and +prepare read-only analysis while decisions are unresolved. It MUST NOT change +release automation, freeze package metadata, publish artifacts, create or move +tags, engage external reviewers, accept legal or security risk, or represent +the Phase 7 entry gate as passed. + +## Decision register + +| ID | Decision | Recommended default | Owner must record | Status | +| --- | --- | --- | --- | --- | +| `P7-OD-001` | Release license | Keep `MIT OR Apache-2.0` through v1 | Exact license expression approved for RC package and release metadata | unresolved | +| `P7-OD-002` | Inbound contribution policy | Choose DCO or CLA with counsel | Selected policy, responsible owner, and effective date | unresolved | +| `P7-OD-003` | Artifact catalogue | Source archive, publishable crates, maintained bindings, WASM/native artifacts, assurance bundle | Exact in-scope and excluded release subjects | unresolved | +| `P7-OD-004` | Registry publication | Prepare all approved subjects; publish only to explicitly approved registries | Registry list and whether the first RC is staged, private, or public in each | unresolved | +| `P7-OD-005` | Supply-chain target | SLSA Build L2 for the first RC | Approved target and any explicitly accepted limitation | unresolved | +| `P7-OD-006` | SBOM baseline | SPDX JSON; retain CycloneDX only as additional evidence | Required SPDX version/profile and optional secondary formats | unresolved | +| `P7-OD-007` | Tag convention | One immutable semver-compatible RC form | Exact tag pattern and initial ordinal policy | unresolved | +| `P7-OD-008` | Release approvers | At least one named human approver distinct from build identity | Named approver or approver role and protected-environment rule | unresolved | +| `P7-OD-009` | Signing identity | GitHub artifact attestation or approved Sigstore identity | Exact issuer, subject, workflow identity, and verification policy | unresolved | +| `P7-OD-010` | Public claim approver | Named technical owner | Approver identity or role and approval-record location | unresolved | +| `P7-OD-011` | Vulnerability and CRA ownership | Name a security contact and obtain counsel review when external EU distribution is in scope | Security contact, disclosure owner, distribution scope, and counsel decision or explicit not-yet-in-scope record | unresolved | + +## Owner response format + +For each decision, record: + +```yaml +decision_id: P7-OD-001 +status: approved +decision: bounded exact decision text +owner: named person or repository role +decided_at: YYYY-MM-DD +evidence_or_advice: optional protected or public reference +conditions: [] +review_at: optional gate or date +``` + +Allowed statuses are `approved`, `deferred`, and `rejected`. `deferred` MUST +name the gate it blocks. A recommendation remains non-binding until an owner +records `approved`. + +Legal, regulatory, trademark, contribution-rights, and licensing decisions +require qualified advice where applicable. Repository text is not legal +advice. + +## Current gate result + +```text +Phase 7 entry: BLOCKED +Unresolved owner decisions: 11 +Release implementation permitted: no +Artifact publication permitted: no +RC tag creation permitted: no +Phase 8 claim publication permitted: no +``` + +The gate may change only through an owner-approved update that resolves every +decision required for the affected Phase 7 surface. diff --git a/docs/plans/PHASE_7_RELEASE_READINESS_AUDIT.md b/docs/plans/PHASE_7_RELEASE_READINESS_AUDIT.md new file mode 100644 index 0000000..47899a7 --- /dev/null +++ b/docs/plans/PHASE_7_RELEASE_READINESS_AUDIT.md @@ -0,0 +1,193 @@ +# Phase 7 release readiness audit + +## Status and reviewed baseline + +Read-only repository audit for AP-SPEC-032. This document records current +implementation facts and gaps; it does not approve owner decisions or +authorize release changes. + +The code and workflow baseline reviewed was `main` at `6f8df76`. The audit was +prepared on the documentation-only specification branch. That branch does not +change release behavior. + +## Governing artifacts + +- [AP-SPEC-032](../specs/0032-reproducible-release-candidate-and-exact-assurance-claim.md) +- [Phase 7 owner decision register](PHASE_7_RELEASE_OWNER_DECISIONS.md) +- [Post-Milestone 6 Productization and Release Plan](../target-state/POST_MILESTONE_6_PRODUCTIZATION_AND_RELEASE_PLAN.md) + +## Current release flow + +```text +push tag matching v* + | + v +.github/workflows/release.yml + | + +-> build and install release toolchains + +-> cargo xtask release-check + +-> reproduce Aeneas translation + +-> upload temporary workflow artifact + +release-check + | + +-> authoritative CI, formal and compliance checks + +-> package 60 publishable Rust crates + +-> smoke-test npm and Python packages + +-> generate platform/compliance evidence + +-> emit CycloneDX 1.5, custom provenance and SHA256SUMS +``` + +This is a strong pre-RC gate, but it builds after the tag event. AP-SPEC-032 +requires the inverse: prepare and verify content-addressed subjects first, then +promote those exact bytes without rebuilding. + +## Existing strengths + +- `.github/workflows/release.yml` pins third-party actions by commit and pins + Rust, Node, Go, Python, Maturin, WASM, Kani, Aeneas, and Charon inputs. +- `cargo xtask release-check` rejects a dirty CI worktree, runs authoritative + CI, all-features and no-default-features tests, documentation, packaging, + formal, architecture, compliance, conformance, binding, and live-demo gates. +- `xtask/src/fixtures.rs::package_check` packages every currently publishable + workspace crate and rejects publishable demo or tooling packages. +- TypeScript and Python packages are built and installed into clean smoke-test + environments. +- `xtask/src/release.rs` records the exact Git commit, toolchain, fixture + manifest, crate subjects, platform artifact, compliance artifacts, and + checksums. +- The release workflow reproduces the pinned Aeneas translation and preserves + formal output. +- `docs/audit/REVIEW_SCOPE.md` already states that no independent review has + been commissioned or completed. + +## Artifact inventory facts + +At the reviewed baseline: + +- the Cargo workspace contains 95 packages; +- 60 packages are publishable by current metadata and 35 declare + `publish = false`; +- all workspace packages use version `0.1.0` and license expression + `MIT OR Apache-2.0`; +- the TypeScript package is `@auths-dev/proof` version `0.1.0`; +- the Python build produces an `auths_proof` wheel; +- `release_evidence()` includes publishable `.crate` archives plus platform + and compliance JSON/text artifacts as checksum and provenance subjects; +- the npm archive, Python wheel, source archive, generated WASM files, formal + evidence, benchmarks, and documentation are not all represented as release + subjects in one manifest; and +- the release workflow uploads `.crate`, `target/release-evidence`, and + `target/formal` paths for 90 days, but does not publish an immutable assurance + bundle. + +The count of publishable packages is a repository fact, not approval to publish +all 60. `P7-OD-003` and `P7-OD-004` must define the actual catalogue and +registry actions. + +## AP-SPEC-032 gap matrix + +| Requirement | Current repository evidence | Gap or decision | +| --- | --- | --- | +| Owner-approved release boundary | Current dual-license metadata and recommendations in the alignment plan | All 11 decisions remain unresolved in the owner register | +| Immutable semantic-freeze inventory | `platform.json`, protocol fixtures, architecture/compliance inventories, bounded-domain and formal manifests | No single schema classifies frozen meaning, frozen bytes, release metadata, and owning paths | +| Drift enforcement | Fixture, architecture, compliance, source-closure, formal, profile, and result-code checks exist | No release-wide rule rejects changed meaning under an unchanged semantic identity | +| Complete artifact catalogue | Cargo metadata and package smoke tests enumerate build outputs | No owner-approved catalogue or explicit exclusion list | +| Content-addressed release manifest | Per-file checksums and custom provenance subjects exist | No AP-SPEC-032 release manifest binding source, semantic freeze, all subjects, evidence, and reproducibility class | +| SPDX SBOM | CycloneDX 1.5 is generated and validated | No SPDX JSON baseline or unambiguous SPDX relationship coverage for every approved subject | +| Signed hosted provenance | Custom unsigned `provenance.json` records GitHub context | Workflow has only `contents: read`; no OIDC `id-token`, artifact-attestation permission, signature, or hosted-build provenance verification | +| Reproducibility classification | Aeneas translation is reproduced twice; WASM/live-demo checks cover selected deterministic artifacts | No per-subject `byte-identical`, `deterministic-evidence`, `platform-reproducible`, or `provenance-only` declaration and two-run comparison | +| Evidence ordering | `release-check` emits evidence; the workflow then runs pinned Aeneas reproduction | Post-check formal output is uploaded but is not necessarily a subject of the earlier release manifest/checksum graph | +| Prepare before tag | Workflow supports dispatch and tag events | Tag push currently starts the build; verified subjects are not staged before tag creation | +| No-rebuild promotion | No registry publication currently occurs | No protected promotion job that downloads subjects by digest and proves no build step ran | +| RC tag contract | `release_check()` requires `GITHUB_REF_NAME == v` for `v*` tags | A semver RC tag such as `auths-proof-v1.0.0-rc.1` or `v1.0.0-rc.1` is not supported by the existing equality rule; exact convention is unresolved | +| Durable evidence bundle | GitHub workflow artifact retained for 90 days | No immutable public bundle, release attachment, OCI artifact, or offline verification package | +| Exact assurance-claim registry | Formal assurance manifest and prose assurance model exist | No registry entry binds every public claim to release subjects, evidence, assumptions, exclusions, and compatibility | +| Claim synchronization | Formal manifest validation and documentation checks exist | No inventory of public claim locations or CI rule rejecting unregistered/stale wording | +| Independent review handoff | `docs/audit/REVIEW_SCOPE.md` defines a baseline scope | AP-SPEC-033 packet, track reports, structured findings, retest, and gate report do not exist and cannot exist before real reviewers engage | + +## Workflow-specific observations + +### Tag and promotion + +`.github/workflows/release.yml` triggers on `push.tags: ["v*"]`. The workflow +checks out the tag and builds release bytes. This cannot satisfy no-rebuild +promotion. `workflow_dispatch` is useful for preparation, but it currently has +no candidate-commit, catalogue, second-run, or publication-mode inputs. + +The workflow does not declare a protected GitHub environment or a distinct +human approval step. Its permission block is read-only, which is safe for the +current non-publishing behavior but insufficient for approved signed +provenance or publication. + +### Subject coverage + +`release_evidence()` derives its subjects from publishable Cargo archives and +selected platform/compliance files. Package smoke tests produce npm and Python +archives elsewhere under `target`, but the evidence generator does not add +those archives to the same subject graph. Formal and benchmark artifacts also +need explicit subject and evidence roles rather than inclusion only by +directory upload. + +### Provenance and SBOM + +The custom provenance is useful internal evidence, but it is generated by the +repository process itself and is not signed hosted-build provenance. The +current CycloneDX document may remain useful as additional evidence; it does +not satisfy AP-SPEC-032's recommended SPDX baseline. + +### Reproduction + +The existing formal translation reproduction is materially stronger than a +single build. AP-SPEC-032 extends this discipline to every approved release +subject. Two isolated preparation runs must start from fresh checkouts and +empty output directories and compare results by the declared class. + +## Decision-to-implementation dependencies + +| Decision | Implementation it blocks | +| --- | --- | +| `P7-OD-001` release license | frozen Cargo/npm/Python metadata and release manifest | +| `P7-OD-002` inbound policy | public contributor recruitment and contributor metadata | +| `P7-OD-003` artifact catalogue | release-subject schema, build graph, SBOM coverage, reproduction matrix | +| `P7-OD-004` registries | promotion workflow, credentials, prerelease behavior, withdrawal procedure | +| `P7-OD-005` supply-chain target | provenance schema, runner and builder requirements, verification policy | +| `P7-OD-006` SBOM baseline | generator choice, SPDX schema/profile, relationship validation | +| `P7-OD-007` tag convention | tag parser, workspace-version rules, promotion input validation | +| `P7-OD-008` release approvers | protected environment, approval record, separation of duties | +| `P7-OD-009` signing identity | workflow permissions, issuer/subject constraints, consumer verification | +| `P7-OD-010` claim approver | Phase 8 approval record and claim-publication gate | +| `P7-OD-011` vulnerability/CRA ownership | public RC distribution, security contact, withdrawal and reporting process | + +## Bounded follow-up PRs after owner approval + +The following are plans, not authorization: + +1. Add the semantic-freeze schema, generator, committed inventory, and drift + tests without changing release publication. +2. Add the owner-approved subject catalogue, release-manifest schema, SPDX + evidence, hosted-provenance contract, and adversarial validators. +3. Add isolated preparation, second-run comparison, content-addressed staging, + and a preparation-only workflow. +4. Add a separate protected no-rebuild promotion workflow for only the + approved registries and signing identity. +5. Close candidate evidence defects, run the exact preparations, and propose + the final candidate revision. +6. Create and promote the immutable RC only through the separately authorized + external event. +7. Add the Phase 8 claim registry and claim-synchronization enforcement against + that fixed RC. + +Each PR must include the tests, affected claims, exclusions, rollback or +withdrawal behavior, and remaining gate conditions required by AP-SPEC-032. + +## Current conclusion + +The repository has unusually strong release inputs: broad authoritative CI, +formal reproduction, package smoke tests, conformance, compliance, checksums, +and internal provenance. The missing work is primarily release-subject +selection, semantic freeze, signed provenance, SPDX coverage, isolated +reproduction, immutable staging/promotion, and exact claim binding. + +No implementation PR may begin until the owner register resolves the decisions +required by AP-SPEC-032. diff --git a/docs/specs/0027-product-grade-typescript-sdk.md b/docs/specs/0027-product-grade-typescript-sdk.md new file mode 100644 index 0000000..fad6d08 --- /dev/null +++ b/docs/specs/0027-product-grade-typescript-sdk.md @@ -0,0 +1,472 @@ +# AP-SPEC-027: TypeScript SDK developer preview + +**Status:** Specified — Phase 10 implementation is blocked on AP-SPEC-032 and +the AP-SPEC-033 Phase 9 exit gate + +**Governs:** The TypeScript developer-preview portion of Phase 10 in the +[Post-Milestone 6 Productization and Release Plan](../target-state/POST_MILESTONE_6_PRODUCTIZATION_AND_RELEASE_PLAN.md) + +**Source strategy:** [Auths Product and Go-to-Market Strategy](../plans/GO_TO_MARKET_STRATEGY.md) + +**Aligned with:** [Post-Milestone-6 Technical and Go-to-Market +Alignment](../plans/POST_MILESTONE_6_TECHNICAL_AND_GO_TO_MARKET_ALIGNMENT.md) + +**Depends on:** AP-SPEC-032, AP-SPEC-033, the reviewed release candidate and +assurance claim, `auths-sdk`, `auths-proof-wasm`, `auths-profile-mcp`, and the +reviewed canonical corpus + +**Scope:** An explicitly labeled, cross-platform TypeScript developer preview +over the reviewed Rust/WASM implementation for attaching an agent, authoring +bounded grants and exact actions, delegating to child agents, verifying +locally, and returning structured decisions on macOS, Linux, Windows, and +supported browsers + +**Normative language:** **MUST**, **MUST NOT**, **SHOULD**, and **MAY** are +requirements on conforming implementations. + +## 1. Decision + +Auths will make the existing `@auths-dev/proof` package the first polished +developer-preview SDK. + +The package currently exposes the portable three-input verifier and a sealed +`VerifiedAction`. Phase 10 will expand that coherent package in place rather +than create a competing TypeScript SDK. Because Auths is prelaunch, the +implementation MAY make a clean API break. It MUST keep the raw verifier +available as an explicit advanced surface. + +The primary activation is: + +> Attach an agent to Auths, give it bounded authority, and protect its first +> action without hand-authoring CBOR or verifier context. + +Rust remains the semantic implementation. TypeScript owns ergonomic workflow, +resource lifetime, and integration types; it MUST NOT reimplement authority, +attenuation, canonicalization, or verification semantics. + +The base SDK MUST run natively on macOS, Linux, and Windows. Platform-specific +custody providers are optional integrations and MUST NOT be required to load, +install, or use the portable authoring and verification surfaces. + +The Phase 10 package MUST remain visibly pre-v1 and developer-preview quality. +It MUST NOT be represented as independently reviewed merely because its Rust +kernel dependency was reviewed in Phase 9; the new binding, workflow, and API +code requires its own tests and later release evidence. + +## 2. Phase placement and entry gate + +Implementation begins only after: + +- AP-SPEC-032 has produced the immutable RC and exact claim bundle; +- AP-SPEC-033 has completed all required review tracks; +- no Phase 9 release block applies to the SDK surfaces or claims; +- the Phase 9 owner approval permits an explicitly labeled developer preview; +- the SDK contract and threat model name every new TypeScript and WASM surface + not covered by the reviewed RC; and +- the release process can distinguish preview packages from stable-v1 + artifacts and claims. + +Phase 10 MAY fix SDK usability and binding defects. A required change to frozen +Rust semantics or reviewed claims returns through AP-SPEC-032 and AP-SPEC-033 +as required by their change classifications. + +## 3. Existing baseline + +The implementation begins from these maintained surfaces: + +- `bindings/typescript` publishes `@auths-dev/proof`; +- `auths-proof-wasm` exposes the supported portable verification boundary; +- `auths-sdk` owns the embedded Rust verifier and product-facing profile + decoding; +- `auths-author` creates external signing requests without owning private keys; +- `auths-custody` defines transaction-bound external signing; +- `auths-profile-mcp` owns exact MCP call canonicalization and verified command + decoding. + +Existing independent TypeScript verification under +`bindings/independent/typescript` remains a differential implementation. It +MUST NOT become the product SDK's authoring or execution implementation. + +## 4. Goals + +The Phase 10 developer preview MUST provide: + +- one idiomatic Node 20+ TypeScript package that runs natively on macOS, + Linux, and Windows, plus its supported browser surface; +- a short `attachAgent` workflow; +- safe parent-agent creation or loading through a signer port; +- bounded grant planning and parent-to-child delegation; +- exact MCP action construction through profile-owned helpers; +- local proof verification through the supported WASM boundary; +- an explicit discriminated union for authorized, denied, and indeterminate + results; +- stable explanations that preserve the kernel stage and code; +- sealed verified commands that cannot be constructed by application code; +- lifecycle-safe cleanup for ephemeral child signers; +- advanced access to canonical bytes, commitments, metrics, and raw results; +- examples and API documentation reproducible from a clean checkout. + +## 5. Non-goals + +The Phase 10 developer preview MUST NOT: + +- build a CLI; +- claim stable-v1 compatibility, production readiness, certification, + compliance, or general availability; +- require an Auths account or hosted service; +- implement a general policy language; +- introduce framework-specific wrappers beyond the MCP adapter needed by the + reference flow; +- implement macOS Secure Enclave or Touch ID support from AP-SPEC-029; +- require hardware-custody feature parity across operating systems; +- persist private keys in the SDK; +- make JavaScript the source of protocol truth; +- collapse MCP, HTTP, Stripe, database, or infrastructure actions into a + generic operation payload; +- turn an authorized result into an automatic side effect; +- hide indeterminate outcomes behind retries or treat them as denials; +- accept arbitrary provider URLs, credentials, or commands. + +## 6. Developer experience + +### 6.1 Installation and first use + +The happy path MUST fit this conceptual shape: + +```ts +import { loadAuths, mcp } from "@auths-dev/proof"; + +const auths = await loadAuths({ signer, trustedAuthority }); + +const parent = await auths.attachAgent({ + name: "research-agent", + runtime: mcp({ service: "records" }), + authority: parentGrant, + approval: { mode: "grant-only", provider: approvalProvider }, +}); + +const child = await parent.delegate({ + name: "records-child", + authority: narrowerChildGrant, + signer: ephemeralSigner(), +}); + +const result = await child.authorize( + mcp.call("update_demo_record", { value: "reviewed" }), +); + +switch (result.kind) { + case "authorized": + await protectedTools.execute(result.command); + break; + case "denied": + case "indeterminate": + report(result.explanation); + break; +} +``` + +Names are illustrative. Implementation review MAY improve them, but the final +API MUST preserve the same stages and security boundaries. + +### 6.2 First-run terminal experience + +The reference example SHOULD make the authority chain visible without +requiring a separate inspector: + +```text ++--------------------------------------------------------------+ +| Auths · attached research-agent | +| Root local-development-root | +| Parent research-agent · durable | +| Child records-child · expires in 10 minutes | +| Authority records / update_demo_record | ++--------------------------------------------------------------+ +| AUTHORIZED complete / authorized | +| Action update_demo_record(value digest 8f...) | +| Proof parent -> child -> exact action | +| Work 3 objects · 2 leaves · 41 work units | ++--------------------------------------------------------------+ +``` + +The SDK MUST expose structured data behind this display. The display MUST NOT +be the only way to recover exact codes or commitments. + +### 6.3 Error behavior + +Developer errors and authorization outcomes are different: + +- invalid SDK construction, malformed configuration, unsupported profile, and + signer protocol violations throw typed SDK errors; +- proof evaluation returns `authorized`, `denied`, or `indeterminate`; +- an authorization outcome MUST NOT throw merely because it is not + authorized; +- error messages MUST NOT include proof bytes, credentials, signatures, + passphrases, or private material; +- explanations MAY add guidance but MUST preserve stable kernel codes exactly. + +## 7. Architecture + +```text ++----------------------------- TypeScript application ----------------------+ +| | +| attachAgent -> delegate -> profile action -> authorize -> closed gateway | +| | | | | | ++-------|------------|-------------|-------------|--------------------------+ + | | | | + v v v v ++----------------------- @auths-dev/proof ------------------------+ +| workflow API | resource lifetimes | typed results | explanations | +| profile facade | signer port | approval port | advanced raw API | ++-------------------------------|----------------------------------+ + v ++------------------------- auths-proof-wasm -----------------------+ +| supported three-input portable verification boundary | ++-------------------------------|----------------------------------+ + v ++---------------------------- Rust core ----------------------------+ +| authoring | canonical model | attenuation | sealed verification | ++-------------------------------------------------------------------+ + +External effects: + +Signer/approval provider <--- exact requests ---> SDK +Closed profile gateway <--- verified command -> provider/tool +``` + +### 7.1 Ownership + +`bindings/typescript` owns: + +- TypeScript workflow classes and interfaces; +- loading and lifetime management of WASM; +- copying at all mutable byte-array boundaries; +- discriminated result types; +- ergonomic explanation text; +- integration examples and generated API documentation. + +Rust product and core packages own: + +- canonical protocol and profile representations; +- grant attenuation and exact action meaning; +- signing preimages; +- trusted-context construction; +- verification and sealed command creation; +- stable result stages and codes. + +Profile packages own: + +- action builders; +- canonicalization; +- verified-command decoders; +- profile-specific denial meaning; +- gateway input types. + +The TypeScript SDK MUST call these implementations through supported bindings. +It MUST NOT duplicate their decision rules. + +### 7.2 Resource and secret boundary + +The SDK MUST define a signer interface that receives only an exact, +domain-separated signing request and returns a signature plus any bound public +evidence. The interface MUST NOT require exporting a private key. + +Development signers MAY exist in test and example code. Their names and +documentation MUST identify them as non-production. Secret bytes MUST be +scoped, cleared where the runtime permits, and excluded from serialization, +logging, fixtures, errors, and receipts. + +An ephemeral child signer MUST expose deterministic disposal. Operations after +disposal MUST fail with a typed local error. + +### 7.3 Sealed execution + +An `authorized` result MUST contain a command whose constructor is unavailable +to application code. The command MUST be derived from the exact canonical +action bytes returned by successful verification. + +A closed gateway accepts that command type. It MUST NOT accept the original +unverified JavaScript object as a substitute. + +### 7.4 Platform portability + +The base package MUST use platform-neutral APIs for paths, temporary storage, +process lifecycle, and WASM loading. It MUST NOT assume POSIX path separators, +Unix sockets, executable permission bits, `/tmp`, a particular shell, or Unix +signal behavior. + +Native provider packages MUST be optional. Importing the base SDK MUST NOT +load, probe, or require a Swift helper or any other platform-specific binary. +Provider selection and capability detection MUST occur explicitly through the +provider interfaces reserved by this SDK and specified fully in AP-SPEC-029. + +Windows support means a native Windows Node process. WSL MAY be supported as a +Linux environment, but it MUST NOT substitute for Windows release evidence. + +## 8. APIs + +The exact names may change during implementation review. The capability split +is normative. + +```ts +export interface AuthsClient { + attachAgent

( + options: AttachAgentOptions

, + ): Promise>; + + verifyRaw(input: RawVerificationInput): VerificationResult; +} + +export interface AttachAgentOptions

{ + readonly name: AgentName; + readonly runtime: RuntimeAdapter

; + readonly authority: SignedGrantSource; + readonly signer: Signer; + readonly approval: ApprovalConfiguration; +} + +export interface AttachedAgent

extends AsyncDisposable { + readonly identity: AgentIdentity; + readonly authority: EffectiveAuthoritySummary; + + delegate( + request: DelegationRequest

, + ): Promise>; + + authorize( + action: P["action"], + ): Promise>; +} + +export interface Signer { + readonly kind: string; + readonly lifecycle: "durable" | "ephemeral"; + publicIdentity(): Promise; + sign(request: SigningRequest): Promise; + dispose?(): Promise; +} + +export interface ApprovalProvider { + approve(request: ApprovalRequest): Promise; +} +``` + +`SigningRequest` and `ApprovalRequest` MUST carry an object kind, semantic +display, exact transaction digest, and opaque signing bytes. A provider MUST +not be allowed to substitute a signature descriptor or mutate the request. + +`ApprovalConfiguration` MUST reserve the four strategy modes. Application code +selects a committed policy reference; it MUST NOT supply an unversioned +decision callback at action time: + +```ts +type ApprovalConfiguration = + | { readonly mode: "grant-only"; + readonly policy: ApprovalPolicyReference; + readonly provider: ApprovalProvider } + | { readonly mode: "risk-based"; + readonly policy: ApprovalPolicyReference; + readonly provider: ApprovalProvider } + | { readonly mode: "every-action"; + readonly policy: ApprovalPolicyReference; + readonly provider: ApprovalProvider } + | { readonly mode: "custom"; + readonly policy: ApprovalPolicyReference; + readonly provider: ApprovalProvider }; + +interface ApprovalPolicyReference { + readonly policyId: string; + readonly evaluatorVersion: string; + readonly configurationDigest: Uint8Array; +} +``` + +The selected policy identity and configuration digest MUST be committed by the +signed grant or trusted context before action use. The SDK MUST verify the +required and executed approval-policy commitments before requesting approval, +signing an approved object, acquiring credentials, or permitting provider I/O. + +The profile or trusted authority MAY impose a minimum supervision requirement. +Host configuration MAY choose an equal or stricter permitted policy before the +grant is committed; it MUST NOT weaken the committed requirement afterward. +A custom policy is a registered, versioned evaluator covered by the committed +reference. Missing, ambiguous, throwing, or mismatched evaluation returns a +typed fail-closed local outcome and produces no signature or effect. + +The Phase 10 preview MAY ship only a deterministic development provider while +reserving these interfaces. Deployable platform providers are governed by +AP-SPEC-029 and Phase 11. + +## 9. Validation and hard limits + +All untrusted inputs MUST be bounded before allocation or WASM invocation. +At minimum: + +- proof, action, and context bytes retain the kernel's configured limits; +- agent names and provider identifiers use a documented ASCII subset; +- delegation depth cannot exceed the trusted-context limit; +- approval display text has a hard byte limit; +- signer evidence count and bytes use the core evidence limits; +- decoded results reject non-canonical, trailing, unknown-version, and + over-depth CBOR; +- mutable `Uint8Array` inputs and outputs are defensively copied. + +The SDK MUST not invent larger limits than the underlying Rust surface. + +## 10. Required evidence + +Implementation MUST add: + +- unit tests for every public discriminated union and typed error; +- canonical positive and negative attach/delegate/authorize fixtures; +- TypeScript-to-Rust agreement for authorized, denied, and indeterminate + outcomes; +- mutation tests proving one changed action byte invalidates authorization; +- tests that application code cannot construct a verified command; +- tests that signer transaction substitution is rejected; +- tests that required and executed approval-policy commitments cannot be + substituted, weakened, omitted, or evaluated ambiguously; +- tests that a failing custom approval evaluator causes no approval prompt, + signature, credential acquisition, or provider I/O; +- tests that disposed ephemeral signers cannot sign; +- browser and Node package smoke tests using the precompiled WASM artifact; +- native Node CI on current supported macOS, Ubuntu Linux, and Windows runners; +- cross-platform tests for paths, temporary resources, child-process cleanup, + optional-provider loading, and unsupported-capability errors; +- package-content tests proving no private fixture or development key ships; +- documentation examples compiled in CI; +- `architecture.toml` and `compliance.toml` updates for every changed consumer. + +## 11. Delivery order + +1. Freeze a TypeScript product API contract and threat model. +2. Add missing Rust/WASM authoring and profile surfaces without duplicating + semantics in TypeScript. +3. Implement signer, approval, agent, and delegation lifecycle interfaces. +4. Implement the MCP action facade. +5. Add sealed command decoding and gateway handoff. +6. Add structured explanations and advanced inspection. +7. Add clean-checkout examples and generated API documentation. +8. Close Node, browser, conformance, architecture, compliance, and packaging + evidence across macOS, Linux, and Windows. + +## 12. Exit gate + +The Phase 10 SDK developer-preview gate is complete only when: + +- a new developer can run the reference attach/delegate/authorize flow without + hand-authoring CBOR; +- the normal path requires no hosted service; +- no private key crosses the verifier boundary; +- authorized, denied, and indeterminate remain distinct public outcomes; +- exact Rust stages and stable codes survive through TypeScript; +- required and executed approval-policy identities and configuration digests + are equal before signing or effectful work; +- TypeScript and Rust agree on all fixtures used by the flow; +- the final package installs and runs from a clean checkout in native Node on + macOS, Ubuntu Linux, and Windows, and in a supported browser; +- the authoritative repository checks pass on the exact revision. + +Passing this gate does not claim stable-v1 compatibility, production custody, +complete MCP execution, production readiness, or commercial readiness. Those +belong to later phases. diff --git a/docs/specs/0028-mcp-delegation-reference-application.md b/docs/specs/0028-mcp-delegation-reference-application.md new file mode 100644 index 0000000..7aa3d34 --- /dev/null +++ b/docs/specs/0028-mcp-delegation-reference-application.md @@ -0,0 +1,469 @@ +# AP-SPEC-028: MCP delegation reference application + +**Status:** Specified — local and reversible Phase 10 implementation is +blocked on AP-SPEC-027 and the AP-SPEC-033 Phase 9 exit gate + +**Governs:** The local MCP reference-vertical portion of Phase 10 in the +[Post-Milestone 6 Productization and Release Plan](../target-state/POST_MILESTONE_6_PRODUCTIZATION_AND_RELEASE_PLAN.md) + +**Source strategy:** [Auths Product and Go-to-Market Strategy](../plans/GO_TO_MARKET_STRATEGY.md) + +**Aligned with:** [Post-Milestone-6 Technical and Go-to-Market +Alignment](../plans/POST_MILESTONE_6_TECHNICAL_AND_GO_TO_MARKET_ALIGNMENT.md) + +**Depends on:** AP-SPEC-032, AP-SPEC-033, AP-SPEC-027, +`auths-profile-mcp`, `auths-proof-exchange`, `auths-enforcement`, and the +existing MCP demo + +**Scope:** An explicitly labeled developer-preview reference application in +which a human-authorized parent agent delegates narrower authority to a child +agent, the child invokes a fixed MCP tool backed by a local constrained HTTP +API, and forbidden actions stop before any external side effect + +**Normative language:** **MUST**, **MUST NOT**, **SHOULD**, and **MAY** are +requirements on conforming implementations. + +## 1. Decision + +Auths will make delegation—not identity verification—the central MCP +demonstration. + +The application will protect one closed records service with exactly three +public MCP tools: + +- `read_demo_record`; +- `update_demo_record`; +- `delete_demo_record`. + +The parent grant permits reading and updating the one configured demo record. +The child receives a narrower, short-lived grant permitting only +`update_demo_record`. The authorized update executes. The delete is a visible +negative control and MUST be terminally denied before credential acquisition +or HTTP execution. + +The tool names are intentionally fixed. The reference application MUST NOT +accept an arbitrary URL, HTTP method, path, header set, credential, record +identifier, or provider command from the agent. + +### 1.1 Phase placement and effect boundary + +Implementation begins only after: + +- AP-SPEC-033 permits the explicitly labeled Phase 10 developer preview; +- AP-SPEC-027 has a pinned preview package and passing exit evidence for the + surfaces used here; +- no unresolved Phase 9 release block affects MCP, exchange, enforcement, + receipt, or binding behavior used by the application; and +- the local record mutation has a deterministic reset and no production data, + credential, tenant, or provider dependency. + +Phase 10 execution is limited to synthetic local state, sandbox state, or +another demonstrably reversible effect approved under AP-SPEC-033. Production +credentials, regulated data, financial effects, infrastructure changes, and +irreversible external mutations are outside this specification. + +## 2. Product claim + +The demo proves this bounded claim: + +> A parent agent can delegate a smaller authority to a child agent; the child +> can exercise the authorized MCP action, cannot exercise a sibling action, +> and cannot gain authority by retrying or restarting. + +It does not prove: + +- that MCP transport authentication is authorization; +- that all MCP tools share the same policy or gateway semantics; +- that Auths prevents a separately credentialed process from calling the HTTP + API; +- exactly-once provider execution without the stated local ledger and provider + precondition; +- production security, independent audit, or universal agent safety. + +The application MUST be described as a developer-preview reference vertical, +not the Phase 13 production flagship or evidence that the new TypeScript and +MCP integration code received the Phase 9 review of the earlier RC. + +## 3. Goals + +The implementation MUST provide: + +- a TypeScript reference agent using AP-SPEC-027; +- a maintained Rust MCP profile and closed verified command; +- parent-to-child attenuation visible in the application; +- a native MCP server or adapter that verifies locally; +- a local constrained HTTP records API with observable mutation state; +- an MCP-specific credential port and least-privilege credential; +- a closed HTTP gateway for each effect; +- profile-owned decision, execution, and observation receipts; +- durable replay and execution state sufficient for restart tests; +- allowed, out-of-scope, expired, replayed, wrong-audience, mutated-action, and + expanded-child scenarios; +- tests proving absence of every forbidden external effect. + +## 4. Non-goals + +The application MUST NOT: + +- become a generic MCP proxy; +- accept arbitrary MCP server definitions or dynamically load tool executors; +- put HTTP execution in `auths-profile-mcp`; +- add MCP variants to a global receipt union; +- use one unscoped `mutation_credential(account)` interface; +- treat tool discovery as authority; +- make a valid signature or authenticated MCP connection sufficient; +- retry an unknown provider outcome as a new action; +- require a hosted Auths service; +- introduce a CLI product surface. + +The demo command used by repository tests MAY remain, but it is not the +product CLI proposed and rejected by the strategy. + +## 5. User experience + +The reference web view or terminal view MUST keep authority, action, execution, +and receipt facts adjacent: + +```text ++------------------------------------------------------------------+ +| Auths MCP delegation demo | +| Human root -> parent-agent -> records-child | ++-------------------------------+----------------------------------+ +| Child authority | Proposed action | +| service: records | tool: update_demo_record | +| expires: 10 minutes | value digest: 8f62... | +| allowed: update only | audience: mcp://records | ++-------------------------------+----------------------------------+ +| [Run authorized update] [Try forbidden delete] [Restart child] | ++------------------------------------------------------------------+ +| AUTHORIZED / DENIED / INDETERMINATE | +| proof -> policy -> claim -> credential -> HTTP -> observation | +| credential requested: no/yes · provider calls: 0/1 | ++------------------------------------------------------------------+ +| Canonical receipt JSON [Receipt details] | ++------------------------------------------------------------------+ +``` + +The happy path and negative control MUST start from visible, reproducible +state. A user MUST be able to see: + +- who delegated to whom; +- what narrowed at each edge; +- the exact MCP tool and argument commitment; +- the required and executed configuration commitments; +- whether a credential was requested; +- whether the HTTP gateway was called; +- whether the record changed; +- the stable denial or indeterminate code; +- the canonical receipt. + +The UI MUST distinguish: + +1. proof authorization; +2. durable execution authorization; +3. HTTP provider acceptance; +4. observed record state. + +These are not one verdict. + +## 6. Architecture + +```text ++----------------------- browser / TypeScript agent ------------------------+ +| human-approved parent -> narrow child -> exact MCP tools/call request | ++------------------------------------|---------------------------------------+ + v ++-------------------------- protected MCP server ----------------------------+ +| bounded MCP decode | +| -> exact auths.mcp/1 canonical action | +| -> local proof verification | +| -> profile-specific policy/effect selection | +| -> durable claim | +| -> profile-scoped credential | +| -> closed verified command | ++-------------------|------------------------------------|------------------+ + | authorized | denied + v v ++------------------- HTTP gateway ----------------+ terminal receipt +| fixed origin + fixed route + fixed method | +| conditional update of configured demo record | ++-------------------|-----------------------------+ + v ++---------------- local records API --------------+ +| record state | revision | provider call counter | ++-------------------|-----------------------------+ + v + observation + receipt +``` + +### 6.1 Package ownership + +`auths-profile-mcp` permanently owns: + +- canonical MCP `tools/call` representation; +- MCP service, tool, arguments, audience, and optional channel binding; +- permission derivation; +- verified MCP command decoding. + +A new cohesive product package or an extension of an existing coherent MCP +product package MUST own this demo's effect semantics: + +- the closed set of records tools; +- the parent and child policy carrier; +- the exact tool-to-effect mapping; +- profile-specific decision codes; +- durable claim and replay behavior; +- the read, update, and delete credential scopes; +- closed HTTP requests; +- observation and reconciliation; +- MCP records receipts. + +The demo owns: + +- the fixed local HTTP service; +- seeded demo state; +- browser or terminal presentation; +- process orchestration; +- adversarial scenario controls; +- end-to-end tests. + +The effect package MUST NOT move MCP or HTTP I/O into `core/`. The demo MUST +not become a dependency of production packages. + +### 6.2 Closed tool mapping + +The trusted server configuration binds: + +| MCP tool | HTTP effect | Resource | +| --- | --- | --- | +| `read_demo_record` | `GET /v1/demo-record` | one configured record | +| `update_demo_record` | `PUT /v1/demo-record` with canonical bounded body | the same record | +| `delete_demo_record` | `DELETE /v1/demo-record` | the same record | + +The agent supplies only the bounded update value for +`update_demo_record`. The route, origin, method, record identity, expected +response schema, and credential scope come from trusted configuration and the +verified command. + +The update request MUST use a revision precondition. A stale revision is +denied or becomes a typed provider conflict according to the profile contract; +it MUST NOT silently overwrite newer data. + +### 6.3 Credential boundary + +Credentials MUST be profile- and effect-scoped: + +```rust +trait UpdateDemoRecordCredentialProvider { + fn update_credential( + &self, + command: &ClaimedUpdateDemoRecord, + ) -> Result; +} +``` + +Read and delete use different interfaces and opaque credential types. The +child's update path MUST NOT be able to obtain a delete credential. + +Credential acquisition occurs only after: + +1. exact proof verification; +2. required/executed configuration equality; +3. profile evaluation; +4. durable decision; +5. atomic replay/execution claim; +6. fresh critical state validation. + +### 6.4 Receipts + +The MCP records profile owns distinct receipt payloads: + +- authorization decision receipt; +- execution transition receipt; +- HTTP provider result receipt; +- observed-state receipt. + +A shared receipt envelope MAY carry stable metadata without erasing these +types. Adding this application MUST NOT require Stripe, GitHub, PostgreSQL, or +other demos to match MCP-specific variants. + +## 7. Authority and policy + +The human root issues a parent grant with: + +- audience `mcp://records`; +- MCP profile V1; +- permission for `read_demo_record` and `update_demo_record`; +- a short bounded validity interval; +- remaining delegation depth at least one; +- an execution budget appropriate to the fixture; +- the committed policy and executed-configuration identity. + +The parent delegates to the child: + +- only `update_demo_record`; +- the same audience; +- a strictly shorter validity interval; +- strictly smaller remaining delegation depth; +- no more execution budget than the parent; +- the same or tighter approval requirements; +- the exact policy/configuration commitment. + +The child MUST be unable to construct a valid expanded grant. Expansion is +rejected by core attenuation before any effect-specific processing. + +## 8. APIs + +### 8.1 MCP tools + +```text +tools/list + -> read_demo_record + -> update_demo_record + -> delete_demo_record + +tools/call read_demo_record {} +tools/call update_demo_record {"value": ""} +tools/call delete_demo_record {} +``` + +The bounded update value MUST: + +- be valid UTF-8; +- be non-empty; +- remain below the profile byte limit; +- reject unknown fields and non-canonical argument representations. + +### 8.2 Demo HTTP routes + +```text +GET /healthz +GET /readyz +GET /api/v1/demo-record +PUT /api/v1/demo-record +DELETE /api/v1/demo-record + +POST /api/v1/scenarios/reset +GET /api/v1/scenarios/current +GET /api/v1/receipts/{receipt_id} +GET /receipts/{receipt_id} +``` + +Mutation routes MUST require the profile-scoped credential and revision +precondition. Scenario-control routes are local-test controls and MUST be +disabled in any public deployment. + +### 8.3 Reference application flow + +```ts +const parent = await auths.attachAgent(parentOptions); +const child = await parent.delegate(updateOnlyChildGrant); + +const allowed = await child.authorize( + mcp.call("update_demo_record", { value: "reviewed" }), +); +if (allowed.kind === "authorized") { + await recordsTools.execute(allowed.command); +} + +const forbidden = await child.authorize( + mcp.call("delete_demo_record", {}), +); +assert(forbidden.kind === "denied"); +``` + +The SDK and gateway MUST make it impossible to pass `forbidden` to +`recordsTools.execute`. + +## 9. Failure semantics + +At minimum, the profile MUST define stable outcomes for: + +- malformed or non-canonical MCP arguments; +- unknown service or tool; +- action digest mismatch; +- expanded child grant; +- expired parent or child grant; +- wrong audience; +- wrong challenge or replay; +- policy commitment mismatch; +- required/executed configuration mismatch; +- stale record revision; +- credential unavailable; +- provider rejection; +- provider outcome unknown; +- observation mismatch; +- duplicate execution claim. + +Retry guidance MUST be explicit. Proof or policy denials are terminal for +unchanged inputs. A restart MUST load the same durable grant and execution +state; it MUST NOT mint fresh authority. + +Unknown provider outcomes retain the execution claim until reconciliation. +They MUST NOT be retried as a new logical action. + +## 10. Test and evidence matrix + +| Scenario | Expected decision | Credential calls | HTTP calls | Record change | +| --- | --- | ---: | ---: | --- | +| Valid child update | authorized and committed | 1 update | 1 PUT | exactly once | +| Child delete | denied | 0 delete | 0 DELETE | none | +| Different service | denied | 0 | 0 | none | +| Mutated update value | denied | 0 | 0 | none | +| Expired child grant | denied | 0 | 0 | none | +| Wrong audience | denied | 0 | 0 | none | +| Expanded child grant | denied | 0 | 0 | none | +| Replay after commit | existing committed receipt | 0 additional | 0 additional | none additional | +| Restart then forbidden delete | same terminal denial | 0 delete | 0 DELETE | none | +| Configuration mismatch | denied before persistence | 0 | 0 | none | +| HTTP response lost after delivery | indeterminate | 1 update | 1 PUT | reconcile | + +Tests MUST observe gateway and API counters or durable request records. Merely +asserting a denied return value is insufficient evidence of no side effect. + +Required coverage: + +- unit and property tests for action bounds and policy tightening; +- canonical fixtures and a mutation corpus; +- denial-before-credential tests; +- exact outbound request equality tests; +- replay, crash, restart, and reconciliation tests; +- Node integration tests through the published package; +- browser end-to-end tests if a browser UI ships; +- architecture and compliance registration; +- authoritative CI on the exact revision. + +## 11. Delivery order + +1. Freeze the MCP records profile and trust claim. +2. Define exact parent and child policies, stable codes, and receipts. +3. Implement the pure profile evaluator and negative corpus. +4. Implement durable claim and restart semantics. +5. Implement separate read, update, and delete credential ports. +6. Implement closed HTTP gateways and the local records service. +7. Integrate the AP-SPEC-027 TypeScript agent flow. +8. Add the adjacent authority/action/receipt presentation. +9. Close adversarial, crash, browser, architecture, compliance, and CI + evidence. + +## 12. Exit gate + +The Phase 10 MCP reference-vertical gate is complete only when: + +- the full happy path works locally from a clean checkout; +- the parent-to-child attenuation is visible and inspectable; +- the permitted update occurs exactly through a verified command; +- every negative scenario proves zero forbidden credential and provider calls; +- a restarted child retains the same authority and denials; +- unknown outcomes reconcile without a second logical execution; +- MCP receipts and credentials remain profile-scoped; +- adding the application does not force unrelated profiles or demos to + understand MCP variants; +- all state and effects remain local, synthetic, sandboxed, or demonstrably + reversible; +- preview labeling and exact reviewed-versus-new code boundaries are visible + in documentation and release evidence; +- the authoritative repository checks pass on the exact revision. + +Passing this gate does not permit consequential customer operation. Phase 11 +runtime, recovery, credential, and deployment gates remain separate. diff --git a/docs/specs/0029-human-approval-and-custody.md b/docs/specs/0029-human-approval-and-custody.md new file mode 100644 index 0000000..f94bfcc --- /dev/null +++ b/docs/specs/0029-human-approval-and-custody.md @@ -0,0 +1,691 @@ +# AP-SPEC-029: Human approval and platform custody + +**Status:** Specified as an umbrella contract — provider-neutral Phase 10 work +is blocked on AP-SPEC-033; deployable custody and packaging are Phase 11 work + +**Governs:** Provider-neutral approval and custody contracts in Phase 10 and +deployable custody work within Phase 11 of the +[Post-Milestone 6 Productization and Release Plan](../target-state/POST_MILESTONE_6_PRODUCTIZATION_AND_RELEASE_PLAN.md) + +**Source strategy:** [Auths Product and Go-to-Market Strategy](../plans/GO_TO_MARKET_STRATEGY.md) + +**Aligned with:** [Post-Milestone-6 Technical and Go-to-Market +Alignment](../plans/POST_MILESTONE_6_TECHNICAL_AND_GO_TO_MARKET_ALIGNMENT.md) + +**Depends on:** AP-SPEC-032, AP-SPEC-033, AP-SPEC-027, `auths-author`, and +`auths-custody`; integration into the MCP reference vertical also depends on +AP-SPEC-028; deployable providers depend on the applicable Phase 11 runtime, +recovery, packaging, and security-assessment gates + +**Scope:** An umbrella for platform-neutral approval and signer contracts, +committed supervision policy, deterministic fake providers, a macOS Secure +Enclave and user-presence reference provider, an explicit software fallback, +a headless signer path, platform packaging, and approval records bound to exact +Auths objects + +**Normative language:** **MUST**, **MUST NOT**, **SHOULD**, and **MAY** are +requirements on conforming implementations. + +## 1. Decision + +Auths will separate three concepts: + +1. **Identity evidence** says how control of a principal is established. +2. **Custody** controls how a private key is stored and used. +3. **Approval** determines when a human or host policy permits an otherwise + valid signing or execution request to proceed. + +Touch ID is an approval mechanism for use of a protected key. A fingerprint is +not an Auths identity and is never key material. + +The first interactive provider will use a macOS Secure Enclave P-256 key where +available. Named parent agents use durable keys by default. Child or +task-specific agents use short-lived or ephemeral signers by default. + +All contracts remain platform-neutral. Native macOS, Linux, and Windows SDK +consumers, headless CI, on-premises deployments, HSMs, KMSs, WebAuthn, and +future operating-system providers MUST be possible without changing authority +or profile semantics. The first release does not require identical +hardware-backed custody on every operating system. + +### 1.1 Phase and change boundaries + +This specification is not one implementation unit. + +Phase 10 may implement only: + +- provider-neutral approval, policy-commitment, record, and custody contracts; +- pure approval-requirement evaluation; +- deterministic fake approval and custody providers; +- adversarial contract and transaction-binding tests; and +- integration into the local, reversible AP-SPEC-028 reference application. + +The macOS helper protocol, Secure Enclave provider, encrypted software +fallback, deployable headless provider, native packaging, key recovery and +rotation, and platform security assessment belong to Phase 11. They MUST NOT +be represented as Phase 10 developer-preview evidence. + +Any provider used during Phase 9 or Phase 10 is limited by AP-SPEC-033's +restricted-preview effect boundary. + +## 2. Product claim + +The bounded claim is: + +> A human can approve issuance or use of an exact Auths authority object, the +> selected custody provider can sign it without exporting a protected private +> key, and the resulting approval is bound to that exact transaction. + +This stage does not claim: + +- that a biometric identifies a legal person; +- that macOS biometric enrollment is an Auths trust root; +- that software fallback is hardware-backed; +- that every operating system offers equivalent protection; +- that approval expands authority; +- that a successful prompt proves the external action succeeded. + +## 3. Goals + +Across its separately gated Phase 10 and Phase 11 work, this specification MUST +provide: + +- one platform-neutral `ApprovalProvider` contract; +- one platform-neutral external signer/custody contract aligned with + `auths-custody`; +- explicit provider capability discovery before custody selection; +- exact approval requests for grant issuance, delegation, and action use; +- configurable `grant-only`, `risk-based`, `every-action`, and `custom` modes; +- a macOS reference provider using Secure Enclave P-256 and user presence; +- a Keychain-backed or passphrase-protected software-key fallback; +- one headless provider contract and reference integration tested on macOS, + Linux, and native Windows; +- durable parent and ephemeral child lifecycle support; +- explicit cancellation, unavailable, rejected, and transaction-mismatch + outcomes; +- signed or otherwise tamper-evident approval records; +- tests proving identity adapters remain independent of custody providers. + +## 4. Non-goals + +Conforming work under this specification MUST NOT: + +- couple Auths to KERI, `did:key`, WebAuthn, or any single identity method; +- store a fingerprint, biometric template, or biometric result; +- claim Touch ID is multifactor authentication without a separately specified + factor model; +- expose general-purpose signing from an Auths custody provider; +- pass arbitrary bytes or user-supplied signature descriptors to a protected + key; +- put platform I/O in `core/`; +- make desktop UI dependencies part of headless builds; +- make the portable SDK depend on any platform-specific native helper; +- read production passphrases from environment variables or command-line + arguments; +- silently fall back from hardware to software custody; +- convert user cancellation into authorization denial; +- build a general CLI. + +## 5. Approval experience + +### 5.1 Grant approval + +The macOS approval sheet SHOULD present the authority a human is actually +granting: + +```text ++--------------------------------------------------------------+ +| Auths · Approve agent authority | ++--------------------------------------------------------------+ +| Agent research-agent | +| May call records/update_demo_record | +| Resource configured demo record | +| Audience mcp://records | +| Valid 10 minutes | +| Delegation may create one child with less authority | +| Supervision grant-only | ++--------------------------------------------------------------+ +| Transaction 7b3d... | +| [Cancel] [Approve with Touch ID] | ++--------------------------------------------------------------+ +``` + +The displayed fields MUST be derived from the same canonical Auths object +whose digest is signed. The provider MUST return that transaction digest with +its result. The caller MUST reject a mismatch. + +### 5.2 Every-action approval + +When `every-action` applies, the approval sheet MUST distinguish an action from +a grant: + +```text ++--------------------------------------------------------------+ +| Auths · Approve exact action | ++--------------------------------------------------------------+ +| Agent records-child | +| Action update_demo_record | +| Change value digest 8f62... | +| Audience mcp://records | +| Expires 30 seconds | ++--------------------------------------------------------------+ +| [Deny] [Approve with Touch ID] | ++--------------------------------------------------------------+ +``` + +The UI MUST not show raw secrets or claim that approval means the provider +effect completed. + +### 5.3 Headless behavior + +A headless deployment receives the same structured `ApprovalRequest`. Its +configured provider may: + +- approve according to a local policy; +- call an on-premises approval system; +- require an externally supplied signed approval artifact; +- reject because interactive approval is unavailable. + +The SDK MUST not open a GUI or switch modes implicitly. + +## 6. Architecture + +```text + exact Auths object + | + v ++---------------------- approval policy -----------------------+ +| grant-only | risk-based | every-action | custom | ++---------------|-------------------------------|---------------+ + | prompt required | no prompt + v | ++---------------------- ApprovalProvider ----------------------+ | +| renders semantic fields | binds transaction | user presence | | ++-------------------------------|------------------------------+ | + v | + ApprovalRecord | + | | + +---------------+----------------+ + v ++-------------------------- auths-custody -----------------------+ +| ExternalSigningRequest -> exact SigningIntent -> signature | +| verifies descriptor and transaction binding | ++---------------------------|------------------|------------------+ + | | + v v + macOS custody helper headless signer + Secure Enclave/Keychain KMS/HSM/local policy + | + v + public signature + +Identity-method adapter verifies principal control independently. +``` + +### 6.1 Ownership + +`auths-author` continues to own exact signing-request construction. + +`auths-custody` owns: + +- provider-neutral signing intent; +- closed supported custody families; +- transaction-bound provider output; +- signer protocol errors; +- signed artifact assembly. + +A new product-layer approval package SHOULD own: + +- approval mode and decision contracts; +- exact approval request and record carriers; +- the pure mode-selection function; +- risk classification inputs without profile-specific risk meaning; +- approval-provider ports. + +The profile or trusted authority owns: + +- the minimum permitted supervision requirement; +- domain-specific risk categories and their canonical inputs; +- required human-readable action details; and +- the schema of approval freshness and reuse constraints. + +The signed grant or trusted context owns the exact selected approval-policy +identity, evaluator version, configuration digest, and applicable freshness or +reuse limit. A host MAY select an equal or stricter permitted policy before the +grant is committed. It MUST NOT weaken or substitute that policy afterward. + +The host owns provider configuration and execution of the committed policy. It +MUST present the required policy and configuration to the runtime as executed +configuration, and the runtime MUST establish exact equality before approval, +signing, credential acquisition, or provider I/O. + +The macOS provider belongs in a dedicated product integration. It MUST NOT +introduce reverse dependencies into core, exchange, or profile packages. + +### 6.2 Approval-policy enforcement + +Approval requirement evaluation is a pure, fail-closed step before provider +invocation: + +```text +profile minimum + trusted grant selection + | + v +required policy ID + version + configuration digest + | + v +registered deterministic evaluator + | + v +required approval rule + freshness + | + v +required configuration == executed configuration + | + +-------+-------+ + | | + v v + approval no prompt required + | | + +-------+-------+ + v + signing/effect pipeline +``` + +An organization-specific policy MUST be a registered, versioned evaluator +whose identity and configuration are committed before action use. An +application-supplied callback, display-only `ruleId`, or mutable host function +is not a security boundary. + +Evaluator absence, exception, ambiguity, timeout, unknown version, digest +mismatch, or output outside the registered schema MUST return a typed +indeterminate or unavailable result. It MUST produce no approval prompt, +signature, credential request, or provider call. + +### 6.3 macOS process boundary + +Repository Rust code forbids `unsafe`. The implementation MUST NOT add an +unchecked Rust FFI shim for the native provider boundary. + +The preferred design is a small, separately built Swift helper communicating +over a bounded, versioned stdin/stdout protocol with a Rust or Node adapter: + +```text +TypeScript SDK + -> bounded local adapter request + -> Swift custody helper + -> CryptoKit / LocalAuthentication / Keychain + -> bounded signed response +``` + +The helper: + +- creates or loads a named Secure Enclave P-256 key; +- stores only an opaque persistent key reference and public metadata; +- sets an access-control policy requiring user presence; +- signs only an Auths domain-separated preimage; +- returns the signature, public key, custody metadata, and transaction digest; +- never returns private key material. + +Adding the native helper requires explicit architecture, dependency, build, +packaging, signing, and release review. The implementation MUST pin the Swift +toolchain expectations and test the packaged artifact, not only source builds. + +### 6.4 Software fallback + +Fallback MUST be explicit in configuration and visible in approval records. + +A conforming fallback: + +- generates a supported Ed25519 or P-256 key using a vetted library; +- encrypts private material at rest with reviewed authenticated encryption and + password-based key derivation parameters; +- stores the encrypted object in Keychain or a protected local store; +- receives passphrases through a callback or protected input channel; +- zeroizes passphrase and plaintext key buffers where the implementation + language permits; +- never logs fallback reason or secret material; +- refuses to reinterpret a hardware key handle as a software key. + +If implementation cannot meet these requirements in TypeScript, the fallback +MUST live in the native helper rather than weaken custody. + +### 6.5 Headless provider + +The headless reference MUST implement `ExternalSigner`; it MAY adapt an +existing KMS, HSM, PKCS#11, SPIFFE workload signer, or a test-only local signer. + +Production examples MUST not accept a secret seed from an environment +variable. They SHOULD accept an opaque provider key identifier and obtain +credentials through the platform's normal workload mechanism. + +### 6.6 Platform support and capability discovery + +The portable SDK and provider contracts MUST operate on macOS, Linux, and +Windows. A provider MUST report its capabilities before the SDK selects or +opens a signer. Capability discovery MUST be read-only and MUST NOT create a +key, display an approval prompt, or silently select a weaker provider. + +The initial platform matrix is: + +| Platform | Required Phase 11 path | Optional or later native path | +| --- | --- | --- | +| macOS | headless/software and Secure Enclave reference provider | additional KMS, HSM, or WebAuthn providers | +| Linux | headless/software provider | TPM2, PKCS#11, Secret Service, KMS, or HSM providers | +| Windows | headless/software provider | CNG, TPM, Windows Hello, KMS, or HSM providers | + +Absence of a native hardware provider MUST be represented as an unsupported or +unavailable capability. It MUST NOT prevent portable authoring, verification, +or use of an explicitly configured headless or software signer. + +## 7. APIs + +### 7.1 Approval request + +```ts +interface ApprovalRequest { + readonly version: 1; + readonly kind: "grant" | "delegation" | "action"; + readonly transactionDigest: Uint8Array; + readonly expiresAt: bigint; + readonly actor: PrincipalSummary; + readonly authority: AuthoritySummary; + readonly action?: ExactActionSummary; + readonly display: ReadonlyArray; +} + +type ApprovalResponse = + | { readonly kind: "approved"; readonly transactionDigest: Uint8Array; + readonly record: ApprovalRecord } + | { readonly kind: "cancelled"; readonly transactionDigest: Uint8Array } + | { readonly kind: "rejected"; readonly transactionDigest: Uint8Array; + readonly code: string } + | { readonly kind: "unavailable"; readonly code: string }; +``` + +Cancellation is a local approval outcome. It MUST NOT be rewritten as a kernel +denial code. + +### 7.2 Approval policy + +```ts +interface ApprovalPolicyCommitment { + readonly policyId: string; + readonly evaluatorVersion: string; + readonly configurationDigest: Uint8Array; +} + +interface ApprovalContext { + readonly request: ApprovalRequest; + readonly effectiveAuthority: EffectiveAuthoritySummary; + readonly requiredPolicy: ApprovalPolicyCommitment; + readonly profileRisk?: ProfileRiskClassification; +} + +type ApprovalRequirement = + | { readonly kind: "not-required"; + readonly policy: ApprovalPolicyCommitment; + readonly ruleId: string; + readonly evaluationDigest: Uint8Array } + | { readonly kind: "required"; + readonly policy: ApprovalPolicyCommitment; + readonly ruleId: string; + readonly freshnessSeconds: number; + readonly evaluationDigest: Uint8Array }; +``` + +The pure selection function MUST be testable without invoking a provider. +Every decision MUST report the committed policy, selected rule, and evaluation +digest. `risk-based` and `custom` decisions MUST use only canonical bounded +inputs covered by that digest. + +Before acting on the result, the runtime MUST compare the required policy +identity, evaluator version, configuration digest, selected rule, and +evaluation digest with the executed values. Any mismatch fails closed before +approval, signing, credentials, or provider I/O. + +### 7.3 Custody provider + +The TypeScript and native surfaces MUST align with the provider-neutral Rust +contract: + +```ts +interface CustodyProvider { + readonly id: string; + capabilities(): Promise; + open(options: CustodyOpenOptions): Promise; +} + +interface CustodyCapabilities { + readonly platform: "macos" | "linux" | "windows" | "other"; + readonly available: boolean; + readonly modes: ReadonlyArray; + readonly unavailableCode?: string; +} + +interface CustodyModeCapabilities { + readonly kind: "secure-enclave" | "software" | "headless"; + readonly hardwareBacked: boolean; + readonly userPresence: boolean; + readonly durableKeys: boolean; + readonly ephemeralKeys: boolean; +} + +interface CustodySigner extends AsyncDisposable { + readonly kind: "secure-enclave" | "software" | "headless"; + readonly lifecycle: "durable" | "ephemeral"; + describe(): Promise; + sign(request: SigningRequest): Promise; +} +``` + +Capability claims MUST describe what the provider can establish, not what the +host operating system might support in theory. `open` MUST fail with a stable, +typed error if the requested capabilities are unavailable or changed after +discovery. It MUST NOT choose an unrequested fallback. + +`SigningResponse` MUST bind: + +- object identifier; +- signature descriptor; +- signature bytes; +- public verification material or reference; +- exact transaction digest; +- acquired evidence; +- hardware-backed and user-presence claims only when established. + +## 8. Approval records + +An approval record MUST contain: + +- schema version; +- approval mode; +- required policy identity, evaluator version, and configuration digest; +- executed policy identity, evaluator version, and configuration digest; +- selected rule identity and evaluation digest; +- required-versus-executed equality result; +- provider kind and implementation identity; +- object kind and object digest; +- transaction digest; +- actor/principal summary; +- approved authority or action summary digest; +- decision time from trusted host input; +- freshness or reuse boundary; +- user-presence result when applicable; +- hardware-backed claim when applicable; +- result kind; +- record signature or integrity commitment. + +It MUST NOT contain: + +- biometric data; +- passphrases; +- private keys; +- raw provider credentials; +- complete sensitive action bodies unless the profile explicitly permits + public receipt disclosure. + +An approval record is evidence that a configured approval step occurred. It +does not replace the signed grant, proof, verification result, or execution +receipt. + +A `not-required` evaluation MUST also produce a policy-evaluation record with +the same required and executed commitments. Absence of a prompt is not absence +of supervision-policy evidence. + +## 9. Failure and fallback semantics + +| Condition | Required behavior | +| --- | --- | +| User cancels | return `cancelled`; produce no signature | +| Biometric unavailable | return `unavailable`; do not silently fall back | +| Hardware key missing | typed unavailable/not-found result | +| Key reference corrupted | fail closed; do not generate a replacement under the same identity | +| Transaction digest mismatch | reject provider output | +| Descriptor substitution | reject provider output | +| Required/executed approval-policy mismatch | fail before prompting, signing, credentials, or provider I/O | +| Custom evaluator missing, ambiguous, throwing, or timed out | typed indeterminate/unavailable result; no effectful work | +| Helper response malformed or oversized | terminate request and fail closed | +| Helper exits after possible signing | return typed unknown local outcome; do not fabricate approval | +| Passphrase incorrect | generic rejection without secret-dependent detail | +| Headless approval required but unavailable | return unavailable; do not auto-approve | + +Fallback may occur only when the host explicitly configured an ordered fallback +policy and the resulting custody kind is shown to the user or operator. + +## 10. Security and privacy requirements + +- Local helper messages MUST have exact schemas, versions, length bounds, and + timeouts. +- Helper executable identity and path MUST be pinned by installation. +- Temporary files MUST NOT carry signing preimages, passphrases, or private + keys. +- Signing and approval prompts MUST resist confused-deputy substitution by + showing the exact semantic object and transaction digest. +- Registered approval evaluators MUST have immutable IDs, versions, bounded + input schemas, configuration digests, and deterministic result schemas. +- Required and executed approval commitments MUST be compared before any + effectful approval, signing, credential, or provider operation. +- Durable key identifiers MUST not contain user PII. +- Logs use opaque request IDs and stable codes. +- Tests and fixtures use unmistakably synthetic keys. +- All secret-bearing Rust types MUST zeroize on drop. +- JavaScript APIs MUST minimize secret residency and document runtime limits on + guaranteed zeroization. +- Key deletion is a separate explicit destructive operation and is outside + normal signer disposal. + +## 11. Required evidence + +Implementation MUST add: + +- pure tests for every approval mode and rule order; +- minimum-supervision tests proving host policy can strengthen but cannot + weaken a committed profile or trusted-authority requirement; +- required/executed approval-policy identity, version, configuration, rule, + and evaluation-digest mismatch tests; +- missing, throwing, ambiguous, timed-out, unknown-version, and noncanonical + custom-evaluator tests proving zero prompts, signatures, credentials, and + provider calls; +- transaction-substitution and descriptor-substitution tests; +- cancellation and unavailable-biometric tests; +- tests proving no signature is returned on failed approval; +- Secure Enclave create/load/sign/restart tests on supported macOS CI or + release hardware; +- explicit evidence when automated CI cannot exercise real biometrics; +- software fallback encryption, corruption, and wrong-passphrase tests; +- headless build tests proving no desktop dependency is linked; +- the platform-neutral provider contract suite on macOS, Linux, and native + Windows CI; +- capability-discovery tests proving probes have no signing, prompting, key + creation, or fallback side effects; +- package tests proving the Swift helper is present and identity-pinned; +- identity-method matrix tests using at least two principal methods with the + same custody provider; +- custody-provider matrix tests using at least two providers with the same + principal method; +- redacted logs and receipt fixtures; +- architecture, compliance, secret-scan, and authoritative CI evidence. + +The two-dimensional matrix is required evidence that identity and custody are +not coupled. + +## 12. Required implementation and pull-request boundaries + +This umbrella MUST be delivered as separately reviewed work packages: + +1. **Phase 10 contract PR.** Freeze approval request, response, policy + commitment, evaluation, record, capability, custody, and error contracts. +2. **Phase 10 fake-provider PR.** Implement deterministic approval and custody + providers and close substitution, mismatch, evaluator-failure, and lifecycle + tests. +3. **Phase 10 reference-integration PR.** Integrate grant-only and every-action + behavior into AP-SPEC-028 using only local reversible effects. +4. **Phase 11 helper-protocol PR.** Specify and implement the bounded, + versioned Swift process protocol and hostile-message tests. No key provider. +5. **Phase 11 Secure Enclave PR.** Implement key creation, persistence, + public-key export, exact signing, user presence, invalidation, and restart. +6. **Phase 11 software-custody PR.** Implement explicit encrypted fallback, + passphrase input, corruption handling, lifecycle, and zeroization evidence. +7. **Phase 11 headless-provider PR.** Implement and test the customer-operated + headless path on macOS, Linux, and native Windows. +8. **Phase 11 packaging and recovery PRs.** Close optional-package loading, + helper identity, signing, upgrade, rotation, backup, recovery, uninstall, + architecture, compliance, and release evidence. +9. **Phase 11 security assessment.** Review the deployable surfaces and retest + remediations before production claims or consequential customer use. + +No PR may combine native helper transport, hardware custody, software custody, +and cross-platform packaging merely because they share this specification. + +## 13. Phase gates + +### 13.1 Phase 10 contract gate + +The provider-neutral Phase 10 work is complete only when: + +- the profile or trusted authority can impose a minimum supervision policy; +- the selected policy ID, evaluator version, configuration digest, selected + rule, and evaluation digest are committed and equality-enforced; +- evaluator failure or ambiguity causes no prompt, signature, credential, or + provider call; +- approval cancellation is distinct from authorization denial; +- deterministic fake providers prove transaction and descriptor binding; +- identity methods remain independent of approval and custody providers; +- AP-SPEC-028 demonstrates grant-only and every-action behavior using only + local reversible effects; and +- authoritative architecture, compliance, contract, and CI checks pass. + +Passing this gate does not establish production custody or permit distribution +of a deployable native provider. + +### 13.2 Phase 11 deployable-custody gate + +Deployable custody work is complete only when: + +- the applicable Phase 11 runtime, recovery, and deployment prerequisites are + complete; +- approval cancellation and unavailable user presence fail safely; +- protected private keys are never exported; +- provider output is bound to the exact Auths transaction; +- a named parent key survives process restart without changing identity; +- ephemeral child disposal prevents future signing; +- headless builds import no desktop or macOS helper dependency; +- the headless/software reference path passes on native macOS, Linux, and + Windows; +- unsupported platform custody is discoverable without preventing portable SDK + use or causing implicit fallback; +- at least two identity methods work independently of at least two custody + providers in the conformance matrix; +- approval records bind required and executed supervision to the intended + grant, delegation, or exact action; +- fallback is explicit and observable; +- packaging, upgrade, rotation, backup, recovery, and uninstall exercises pass; +- the deployable surfaces complete their scoped security assessment and + remediation gate; and +- authoritative repository and platform release checks pass on the exact + revision. + +Phase 11 does not require a CLI, hosted approval service, hardware-backed +Windows or Linux provider, mobile provider, equal native custody features on +every platform, or a general enterprise key-management product. diff --git a/docs/specs/0030-design-partner-integrations.md b/docs/specs/0030-design-partner-integrations.md new file mode 100644 index 0000000..47d3563 --- /dev/null +++ b/docs/specs/0030-design-partner-integrations.md @@ -0,0 +1,508 @@ +# AP-SPEC-030: Design-partner integration program + +**Status:** Specified as a phased program — recruitment begins during Phase 9, +restricted integrations begin under Phase 9–10 gates, and consequential +customer pilots wait for Phase 11 + +**Governs:** Design-partner recruitment and restricted integration during +Phases 9–10, customer-operated pilots after Phase 11, and flagship evidence in +Phase 13 + +**Source strategy:** [Auths Product and Go-to-Market Strategy](../plans/GO_TO_MARKET_STRATEGY.md) + +**Aligned with:** [Post-Milestone-6 Technical and Go-to-Market +Alignment](../plans/POST_MILESTONE_6_TECHNICAL_AND_GO_TO_MARKET_ALIGNMENT.md) + +**Depends on:** AP-SPEC-032 for recruitment; AP-SPEC-033 for restricted Phase 9 +preview; AP-SPEC-027 and AP-SPEC-028 for Phase 10 integration; and the +applicable AP-SPEC-029 and Phase 11 runtime, recovery, and security gates for +consequential pilots + +**Scope:** A repeatable program for integrating Auths with agent-framework +maintainers and teams building internal agents, measuring product friction, +and converting repeated integration work into evidence for the next product +surface + +**Normative language:** **MUST**, **MUST NOT**, **SHOULD**, and **MAY** are +requirements on the program and any supporting implementation. + +## 1. Decision + +Auths will recruit design partners during independent review, integrate them +against restricted developer-preview surfaces, and widen effects only as the +technical program earns the required runtime and recovery gates. + +The program is not a sales-logo exercise. Each integration must exercise +bounded delegation in a maintained agent workflow, produce a structured +integration diary, measure the time and friction involved, and test whether +developers can understand failures without reading verifier internals. + +The program will recruit from two initial groups: + +1. maintainers of agent frameworks, runtimes, or MCP tooling; +2. platform teams building internal agents that perform real tool or HTTP + actions. + +At least two integrations must become maintainable by two people outside the +Auths core project before the program can close. + +## 2. Product questions + +The program exists to answer: + +- Can a developer attach an existing agent without becoming an Auths protocol + expert? +- Is parent-to-child delegation valuable in a real workflow, or do users only + adopt identity verification? +- Which SDK concepts cause the most confusion or custom code? +- Which authorization denials are difficult to diagnose? +- Which approval modes match hobbyist, internal, and regulated workflows? +- Which operational tasks recur across organizations? +- Do users need a CLI, visual inspector, hosted service, on-premises control + plane, receipt search, policy distribution, or framework adapter? +- Who owns implementation and operation inside the organization? + +Answers must be supported by observed behavior or explicit partner evidence. +Internal intuition alone does not close a question. + +## 3. Goals + +The program MUST produce: + +- a documented partner-selection rubric; +- a standard onboarding and security-review packet; +- several real SDK integrations; +- one integration diary per partner; +- setup-time, failure, and support measurements; +- an inventory of all custom adapter and glue code; +- redacted authority, delegation, and denial examples; +- a repeated-needs synthesis; +- decisions to improve, defer, or reject candidate product surfaces; +- at least two integrations maintained by independent non-core contributors. + +## 4. Non-goals + +The program MUST NOT: + +- promise a hosted service, control plane, CLI, connector, or compliance + feature before evidence supports it; +- bypass an integration's native authorization or provider controls; +- import customer-specific semantics into `core/`; +- turn partner code into a generic executor; +- collect proofs, action bodies, credentials, receipts, or identity data + through mandatory telemetry; +- treat interviews without usage as proof of product behavior; +- count a demo run by an Auths maintainer as external maintenance; +- publish a partner's name, architecture, metrics, or security details without + explicit permission; +- accept custom changes that weaken local verification or open-core + independence. +- expose a production credential, regulated dataset, financial mutation, + infrastructure mutation, or irreversible customer effect before the + applicable Phase 11 gate; +- describe Phase 9 or Phase 10 restricted use as a production pilot. + +## 5. Partner selection + +Each candidate is scored against: + +| Criterion | Required evidence | +| --- | --- | +| Active agent workflow | An agent currently calls at least one real tool or API | +| Authority problem | Existing credential or permission is broader than the task | +| Delegation fit | Parent, orchestrator, workflow, or sub-agent can delegate less | +| Maintainer access | A technical owner can work directly with the SDK | +| Test environment | Side effects can be exercised safely and observed | +| Commitment | Partner agrees to a bounded implementation and feedback cycle | +| Learning value | Workflow differs materially from completed integrations | + +The first cohort MUST recruit three to five integrations and include: + +- at least one framework or runtime maintainer; +- at least one internal-agent platform team; +- at least one autonomous, grant-only workflow; +- at least one strongly supervised workflow. + +At least two participants MUST have maintainers capable of updating and +operating their integration without the core author. + +Regulated organizations MAY participate, but Auths MUST not claim regulatory +compliance merely because they do. + +### 5.1 Phase and effect-risk gates + +| Lane | Earliest gate | Permitted effect | +| --- | --- | --- | +| Recruitment and problem mapping | AP-SPEC-032 complete and Phase 9 active | no Auths-controlled provider effect required | +| Restricted review preview | AP-SPEC-033 Section 11 conditions | synthetic, local, sandboxed, read-only, draft, or demonstrably reversible | +| Phase 10 measured integration | AP-SPEC-027/028 preview gates | pinned preview artifacts and restricted effects only | +| Customer-operated pilot | applicable Phase 11 runtime, custody, recovery, and security gates | explicitly reviewed bounded customer effect | +| Flagship evidence | Phase 13 | continuously operated reviewed flagship workflow | + +An effect cannot move to a later lane merely because a partner accepts the +risk. The technical gate, credential boundary, recovery behavior, data rules, +and written charter MUST all permit it. + +## 6. Integration experience + +### 6.1 Partner journey + +```text ++----------------------------------------------------------------+ +| 1. Map one real action | +| agent -> tool -> credential -> side effect -> observation | ++-------------------------------+--------------------------------+ + v ++----------------------------------------------------------------+ +| 2. Define authority | +| root -> parent -> child -> exact action | ++-------------------------------+--------------------------------+ + v ++----------------------------------------------------------------+ +| 3. Integrate SDK and closed gateway | +| attach -> delegate -> authorize -> execute -> receipt | ++-------------------------------+--------------------------------+ + v ++----------------------------------------------------------------+ +| 4. Run adversarial cases | +| expanded, expired, replayed, mutated, wrong audience | ++-------------------------------+--------------------------------+ + v ++----------------------------------------------------------------+ +| 5. Partner maintains and explains it | +| clean setup -> diagnose denial -> update dependency | ++-------------------------------+--------------------------------+ + v ++----------------------------------------------------------------+ +| 6. Record evidence and repeated needs | ++----------------------------------------------------------------+ +``` + +### 6.2 Action-mapping worksheet + +Before code changes, the partner and Auths maintainer MUST identify: + +- the exact external effect; +- current agent and human actors; +- current credential holder and scope; +- trusted and untrusted inputs; +- the narrowest useful parent authority; +- the child attenuation; +- action canonicalization; +- approval mode; +- closed gateway and credential timing; +- observable evidence that the side effect did or did not happen; +- retry, restart, and unknown-outcome behavior; +- sensitive fields that must not enter receipts or research artifacts. + +If the workflow requires unrelated effects with different credentials, +evidence, or lifecycle semantics, they are separate profiles or integration +slices. + +## 7. Architecture + +```text ++---------------------- auths-proof ----------------------+ +| cohesive product integration | +| exact action -> evaluator -> verified command | +| credential port -> closed gateway -> domain receipt | ++---------------------------|------------------------------+ + | pinned published contracts + v ++-------------------- partner repository -----------------+ +| agent/framework -> Auths SDK -> non-semantic adapter | +| local wiring/configuration -> existing tool/provider | ++---------------------------|------------------------------+ + | + | local, opt-in measurements + v ++---------------- integration evidence bundle -------+ +| timing summary | friction log | denial exercises | +| adapter inventory | maintenance handoff | ++----------------------|-----------------------------+ + v ++---------------- Auths synthesis --------------------+ +| repeated needs | rejected ideas | product decisions| ++----------------------------------------------------+ +``` + +Customer repositories MUST consume published or explicitly pinned Auths +artifacts. They MUST NOT use mutable sibling path dependencies. + +Partner repositories MAY own only non-semantic integration code during this +program, including: + +- framework and runtime adapters; +- application wiring and configuration; +- UI and developer-experience code; +- provider SDK plumbing behind an Auths-owned closed port; and +- partner-local test harnesses and synthetic fixtures. + +New exact effects and security semantics MUST begin in one cohesive Auths +product integration under `product/integrations/auths-/`. This includes +canonical actions, policy and evidence types, evaluators, verified commands, +credential ports and scopes, gateways, lifecycle transitions, reconciliation, +stable codes, and receipt meaning. + +Partner-specific non-semantic code remains in the partner repository unless it +is: + +- generally useful; +- semantically identical to an existing Auths contract; +- accepted through normal architecture and conformance review; +- free of partner secrets, endpoints, and proprietary policy. + +Before Phase 12 conformance machinery exists, a partner repository MUST NOT +become the sole owner of new Auths security semantics. After Phase 12, an +independently maintained external profile MAY own semantics only through the +versioned profile SDK and conformance process; it does not thereby become part +of Auths' formal or provider-correctness claim. + +### 7.1 Measurement boundary + +Measurements are local and opt-in. The default implementation writes a +redacted summary that the partner reviews before sharing. + +The measurement layer MAY record: + +- named workflow step; +- monotonic duration; +- result kind, stage, and stable code; +- count of configuration steps; +- count and category of custom adapter lines; +- count of support interventions; +- SDK and profile versions. + +It MUST NOT record: + +- raw proofs or canonical actions; +- credentials or key identifiers; +- action bodies; +- person or organization identity; +- private repository, patient, financial, or customer data; +- receipts unless separately reviewed and redacted. + +## 8. Program artifacts + +Each integration receives an opaque identifier such as `partner-004`. Public +and repository artifacts use that identifier unless naming permission is +recorded. + +### 8.1 Integration brief + +```yaml +schema: auths.design-partner-brief/1 +integration_id: partner-004 +segment: internal-agent-team +workflow_summary: bounded non-sensitive description +profile: auths.mcp/1 +authority_shape: parent-to-child +approval_mode: risk-based +deployment: local +success_effect: bounded non-sensitive description +owner_role: platform-engineer +``` + +No contact information belongs in the repository artifact. + +### 8.2 Integration diary + +The diary MUST record: + +- baseline architecture and permission problem; +- initial SDK version and documentation used; +- each integration session and elapsed active time; +- confusing concepts and API failures; +- custom adapter code and why it exists; +- all denial scenarios attempted; +- whether the partner diagnosed each failure unaided; +- approval and custody configuration; +- deployment constraints; +- maintenance handoff result; +- candidate product needs in the partner's own words; +- explicit redactions. + +### 8.3 Metrics summary + +```json +{ + "schema": "auths.design-partner-metrics/1", + "integration_id": "partner-004", + "sdk_version": "0.x", + "minutes_to_first_authorized_action": 0, + "minutes_to_first_delegation": 0, + "manual_artifact_count": 0, + "custom_adapter_line_count": 0, + "support_intervention_count": 0, + "denial_cases_attempted": 0, + "denial_cases_diagnosed_without_help": 0, + "maintained_by_partner": false +} +``` + +Zeroes in the example are placeholders, not targets. + +### 8.4 Repeated-needs register + +Every candidate need is recorded with: + +- problem statement; +- affected integrations; +- current workaround; +- frequency and severity; +- proposed owning layer; +- whether it requires hosted or on-premises infrastructure; +- open-core impact; +- evidence for and against building it; +- decision: build, investigate, defer, or reject. + +## 9. APIs and integration contract + +Partners use only published SDK and profile APIs. + +The minimum integration contract is: + +```ts +interface DesignPartnerIntegration

{ + readonly id: string; + readonly profile: P; + + attach(): Promise>; + runAuthorizedScenario(): Promise; + runDeniedScenarios(): Promise>; + verifyNoForbiddenEffects(): Promise; +} +``` + +This interface MAY exist only in the design-partner testkit. It MUST NOT become +a production framework that dispatches provider behavior. + +`ScenarioEvidence` contains result kind, stable stage/code, redacted +commitments, credential-call count, provider-call count, and observed effect. +It contains no secrets or arbitrary partner payload. + +## 10. Evaluation protocol + +Each partner integration runs four reviews: + +### Review A: Baseline + +- observe the current workflow; +- record existing credential breadth; +- identify one exact effect; +- agree on the bounded Auths claim. + +### Review B: Assisted integration + +- partner follows published documentation; +- Auths maintainer observes but does not preempt every error; +- diary records setup time and interventions. + +### Review C: Adversarial and restart exercise + +- valid delegated action; +- expanded child authority; +- mutated action; +- expired grant; +- wrong audience; +- replay; +- restart followed by forbidden action; +- domain-specific unknown outcome when applicable. + +### Review D: Maintenance handoff + +- partner rebuilds from a clean checkout; +- partner diagnoses an intentional denial; +- partner updates one non-semantic configuration value; +- partner identifies where authority, execution, and receipts are represented; +- partner assumes normal maintenance responsibility. + +## 11. Product-change policy + +Partner feedback MAY trigger SDK improvements immediately when the change: + +- clarifies an existing concept; +- removes accidental setup work; +- preserves protocol and profile meaning; +- adds focused tests and documentation. + +New product surfaces require repeated evidence. As a default: + +- one integration establishes a problem report; +- two independent integrations justify focused investigation; +- three integrations spanning at least two organizations justify a product + proposal; +- semantic abstraction still follows the stricter profile/domain extraction + gates. + +Urgent security defects bypass product-discovery thresholds and follow the +security process. + +## 12. Required evidence + +The program MUST retain: + +- reviewed integration briefs and diaries; +- redacted metric summaries; +- exact SDK/profile versions; +- clean-checkout reproduction steps; +- adversarial scenario results; +- effect-call evidence; +- maintenance handoff evidence; +- a synthesis separating repeated needs from one-off requests; +- decisions and their supporting evidence. + +Private partner materials MAY live outside the public repository. The public +record should retain only redacted findings and opaque evidence identifiers. + +## 13. Program gates + +### 13.1 Recruitment gate + +Recruitment is ready when: + +- three to five partners have signed the bounded participation charter; +- the cohort covers both initial user groups and both autonomous and strongly + supervised operation; +- each proposed effect has an assigned risk lane and data boundary; +- at least two participants name a non-core maintainer; and +- no charter promises production, compliance, certification, hosted service, + or unsupported effect scope. + +### 13.2 Restricted-integration gate + +Restricted integration evidence is sufficient to inform SDK iteration when: + +- at least three real integrations complete the applicable evaluation protocol; +- at least one framework or runtime maintainer and one internal-agent team are + represented; +- multiple partners use parent-to-child delegation rather than identity alone; +- at least two integrations are maintained by two people outside the Auths core + project; +- developers diagnose the standard negative cases without reading verifier + internals; +- setup time, friction, adapter work, and support interventions are measured; +- new security semantics remain in cohesive Auths product integrations; +- every effect stayed inside its permitted technical and risk lane; +- the repeated-needs register identifies evidence-supported candidates for + AP-SPEC-031; and +- no mandatory telemetry or hosted verification dependency was introduced. + +### 13.3 Customer-pilot and program exit gate + +The full design-partner program closes only when: + +- the applicable Phase 11 runtime, custody, recovery, deployment, and security + gates passed before consequential customer operation; +- at least one customer-operated integration completed backup, restore, + upgrade, rotation, interruption, ambiguous-outcome, and incident-diagnosis + exercises; +- at least one reviewed flagship workflow has operated under the Phase 13 + conditions; +- external maintainers can upgrade and operate at least two integrations; +- every finding and effect-risk exception has an owner and disposition; and +- repeated integration and operational evidence is sufficient for AP-SPEC-031 + to select a paid product or record a disciplined no-build decision. + +No specific CLI, hosted, on-premises, governance, or pricing decision is +required. The purpose of this program is to earn those decisions. diff --git a/docs/specs/0031-commercial-discovery.md b/docs/specs/0031-commercial-discovery.md new file mode 100644 index 0000000..a24f660 --- /dev/null +++ b/docs/specs/0031-commercial-discovery.md @@ -0,0 +1,501 @@ +# AP-SPEC-031: Commercial discovery and product selection + +**Status:** Specified as a parallel evidence program — problem, buyer, and +deployment discovery begins during Phase 7; product selection remains gated on +integration and willingness-to-pay evidence + +**Governs:** Commercial discovery from Phase 7 onward and the later evidence +gate for selecting at most one initial paid-product problem + +**Source strategy:** [Auths Product and Go-to-Market Strategy](../plans/GO_TO_MARKET_STRATEGY.md) + +**Aligned with:** [Post-Milestone-6 Technical and Go-to-Market +Alignment](../plans/POST_MILESTONE_6_TECHNICAL_AND_GO_TO_MARKET_ALIGNMENT.md) + +**Depends on:** Approved research privacy and consent operations for early +discovery; AP-SPEC-030 and its repeated-needs register for integration-backed +selection; and recorded owner decisions for any exact license, package, +repository, or commercial boundary + +**Scope:** A disciplined commercial-discovery program for identifying the +economic buyer, deployment preference, budgeted operational problem, initial +paid product, packaging, and willingness to pay without weakening the open +protocol + +**Normative language:** **MUST**, **MUST NOT**, **SHOULD**, and **MAY** are +requirements on the discovery process and its evidence. + +## 1. Decision + +Auths will not choose its first paid product from a speculative feature list. + +Commercial discovery begins during Phase 7 with problem, buyer, current- +workflow, deployment, procurement, and willingness-to-pay research. It does +not wait for the SDK. + +Demonstrated use of the SDK, delegation flow, and customer-operated runtime is +required later to validate solution behavior and product selection. Interviews +can identify a problem; they cannot prove that the proposed Auths product +solves it. + +Candidate products include: + +- approval workflow service; +- agent and grant fleet inventory; +- durable receipt retention, search, and export; +- policy distribution and lifecycle operations; +- managed connectors; +- hosted organization and trust management; +- on-premises enterprise control plane; +- support, deployment, and assurance packages. + +This list is a hypothesis set, not a roadmap. The selection gate chooses at +most one initial product problem for committed build planning. + +### 1.1 Phase lanes + +| Lane | Timing | Permitted output | +| --- | --- | --- | +| Problem and buyer discovery | Phase 7 onward | interview and workflow evidence, buyer and deployment hypotheses | +| Claim and trust-language testing | Phases 8–9 | reactions to the exact assurance boundary without production promises | +| Integration observation | Phases 9–10 | restricted design-partner behavior and repeated-needs evidence | +| Operational and solution validation | Phase 11 onward | customer-operated workflow, deployment, support, and recovery evidence | +| Product selection | after all decision gates pass | one PRD or a no-build decision | + +Discovery may continue across all lanes. A later lane does not retroactively +upgrade weak evidence from an earlier one. + +## 2. Commercial doctrine and provisional boundaries + +The business model MUST preserve these constraints: + +- local verification remains useful without an Auths-operated service; +- the open local path required to author, delegate, verify, enforce safely, and + inspect evidence is not crippled to force conversion; +- hosted and on-premises deployment are both testable; +- commercial value comes from operations, coordination, governance, + integration, support, and service; +- pricing does not discourage correct local verification; +- identity-method, transport, and cryptographic agility remain intact; +- customer evidence, not desired valuation, determines the first offer. + +These are architectural and product constraints. They do not decide the exact +license, which packages or repositories contain commercial code, the first +paid product, deployment topology, pricing metric, price, support commitment, +or certification program. + +Those exact boundaries remain provisional until the named owner records the +decision at the applicable gate. Research artifacts MUST label them +`hypothesis`, `recommended`, or `owner-approved`. An executing agent MUST NOT +turn a recommendation into code, licensing changes, publication, or a customer +promise. + +## 3. Questions to answer + +The program MUST answer: + +1. Who feels the operational pain strongly enough to sponsor a purchase? +2. Who uses Auths day to day, who approves deployment, and who controls budget? +3. Which repeated problem cannot be solved adequately with the open SDK alone? +4. Is that problem urgent, frequent, and expensive? +5. Is the required product hosted, on-premises, hybrid, or deployment-neutral? +6. What security, privacy, procurement, and support requirements govern it? +7. What outcome would a buyer pay to obtain? +8. What unit of value makes pricing understandable? +9. What free/open boundary maintains trust and adoption? +10. Which candidate should be explicitly rejected or deferred? + +## 4. Goals + +The program MUST produce: + +- a hypothesis ledger that begins with early research and is later reconciled + with AP-SPEC-030 integration evidence; +- a map of users, champions, security reviewers, operators, and economic + buyers; +- problem interviews and workflow observations; +- hosted, on-premises, and hybrid deployment evidence; +- solution tests using low-cost prototypes or service simulations; +- willingness-to-pay evidence; +- a documented open-core boundary test for each candidate; +- one evidence-backed first commercial product decision or an explicit + no-build decision; +- a follow-on product requirements document only after selection. + +## 5. Non-goals + +The program MUST NOT: + +- assign arbitrary ARR, valuation, customer-count, or market-share targets; +- turn expressions of interest into booked demand; +- count free implementation help as willingness to pay; +- build several candidate products in parallel; +- sign long-term commitments for unimplemented capabilities; +- make compliance certifications or legal guarantees; +- require hosted verification; +- move customer policy or operational state into the open kernel; +- collect sensitive customer artifacts in the public repository; +- optimize for GitHub stars, impressions, or downloads as commercial proof; +- build a CLI because one interviewee casually requests one. + +## 6. Discovery journey + +```text ++-----------------------------+ +-----------------------------+ +| Early discovery | | Design-partner evidence | +| problem + buyer + workflow | | usage + repeated needs | ++---------------|-------------+ +--------------|--------------+ + +--------------------+------------+ + v ++---------------------------------------------------------------+ +| Problem validation | +| observe workflow -> quantify pain -> identify buyer | ++-------------------------------+-------------------------------+ + v ++---------------------------------------------------------------+ +| Deployment and trust test | +| local only | hosted | on-premises | hybrid | ++-------------------------------+-------------------------------+ + v ++---------------------------------------------------------------+ +| Solution test | +| mockup/service simulation -> buyer commitment | ++-------------------------------+-------------------------------+ + v ++---------------------------------------------------------------+ +| Open-core and economics review | +| value unit -> packaging -> willingness to pay | ++-------------------------------+-------------------------------+ + v ++---------------------------------------------------------------+ +| Select one product, continue discovery, or do not build | ++---------------------------------------------------------------+ +``` + +### 6.1 Problem interview + +The researcher SHOULD begin from observed behavior: + +- “Show me how agent authority is issued and changed today.” +- “What happens when a person leaves or an agent is replaced?” +- “How do you find which agents can call a particular tool?” +- “How do you approve a high-risk action?” +- “How do you investigate a denied or disputed action?” +- “Which evidence do security, audit, or operations teams require?” +- “Which parts must remain inside your infrastructure?” +- “What have you built or paid for to solve this already?” + +The researcher MUST not lead with the candidate product or ask only whether it +sounds useful. + +### 6.2 Solution test + +A solution test MAY use: + +- a clickable mockup; +- a manually operated concierge workflow; +- a static sample report; +- a local prototype over synthetic data; +- an architecture and deployment review; +- a paid design engagement. + +It SHOULD avoid production implementation until the buyer, problem, and +deployment model are supported by evidence. + +## 7. Evidence model + +### 7.1 Evidence strength + +Evidence is ranked from weakest to strongest: + +| Level | Evidence | +| --- | --- | +| E0 | Internal belief or analogy | +| E1 | Prospect states a preference | +| E2 | Prospect demonstrates the current workflow and pain | +| E3 | Prospect invests meaningful engineering or security-review time | +| E4 | Prospect agrees to a scoped pilot with success criteria | +| E5 | Prospect signs a paid pilot, purchase order, or equivalent commitment | + +Product selection requires E2 observations from at least three independent +organizations, at least one E3 commitment, and a credible path to E4. Pricing +confidence requires E4 or E5 evidence; hypothetical price reactions alone are +insufficient. + +### 7.2 Hypothesis ledger + +```yaml +schema: auths.commercial-hypothesis/1 +hypothesis_id: H-012 +candidate_product: receipt-operations +segment: internal-agent-platform +problem: bounded non-sensitive statement +user_role: platform-engineer +buyer_role: security-platform-lead +deployment_requirement: on-premises +value_unit: retained-and-searchable-action-receipts +evidence_for: + - evidence_id: partner-004-observation-7 + level: E2 +evidence_against: [] +status: testing +next_test: bounded non-sensitive description +``` + +Evidence identifiers point to access-controlled research material where +necessary. No personal contact information, customer secrets, proof bodies, or +credentials belong in the repository ledger. + +### 7.3 Interview record + +Each record MUST capture: + +- opaque organization and participant identifiers; +- participant role in the workflow and purchase; +- current process; +- frequency and consequence of the problem; +- existing workaround and cost; +- security and deployment constraints; +- evidence level; +- direct factual observations; +- researcher interpretation, clearly separated; +- candidate invalidations; +- consent and redaction status. + +## 8. Candidate-product architecture tests + +Every candidate must be evaluated against the open-core architecture before +commercial selection. + +```text ++--------------------------- customer system --------------------------+ +| agent -> open Auths SDK -> local verifier -> closed customer gateway | ++-------------------------------|--------------------------------------+ + | + | optional operational integration + v ++-------------------- candidate commercial product --------------------+ +| governance | inventory | workflows | retention | connectors | support| ++-----------------------------------------------------------------------+ + +No commercial product may sit on the mandatory local verification path. +``` + +For each candidate, record: + +- data it receives; +- data it stores; +- authority it can change; +- failure behavior when unavailable; +- hosted, on-premises, and hybrid topology; +- tenant and operator trust boundaries; +- export and deletion requirements; +- integration and credential boundaries; +- whether the open SDK remains fully useful without it; +- package and repository ownership if eventually built. + +A candidate fails the architecture test if unavailability prevents ordinary +local verification, unless the customer explicitly configured that external +service as an additional approval-policy requirement. + +## 9. Candidate scorecard + +Candidates are compared using evidence, not weighted to force a predetermined +winner: + +| Dimension | Required interpretation | +| --- | --- | +| Problem evidence | Number and strength of independent observations | +| Buyer clarity | Identified role with authority and budget | +| Urgency | Consequence and deadline of leaving the problem unsolved | +| Frequency | How often the workflow occurs | +| Existing spend | Money or engineering time already committed | +| Open-core fit | Paid value does not cripple local open use | +| Deployment fit | Hosted/on-premises model satisfies observed constraints | +| Product leverage | Reuses stable SDK/protocol surfaces | +| Semantic risk | Does not create a generic executor or policy engine | +| Delivery risk | Scope can reach a meaningful pilot | +| Defensibility | Compounds integrations, operational trust, or assurance | +| Evidence against | Explicit reasons not to build | + +Scores MUST link to evidence identifiers and include a confidence rating. +Unresolved assumptions remain visible. + +## 10. Packaging and willingness-to-pay tests + +Pricing is tested after the problem and buyer are credible. + +The program SHOULD test: + +- which outcome is purchased; +- whether value is per organization, deployment, managed connector, governed + agent fleet, approval workflow, retained receipt volume, or support level; +- whether local verification remains unmetered; +- whether a hosted and on-premises edition require different packaging; +- pilot scope and success criteria; +- procurement and support expectations. + +The program MUST distinguish: + +- a price a prospect says is reasonable; +- a budget range they control; +- an approved pilot; +- a signed commercial commitment. + +Only the last two materially validate willingness to pay. + +## 11. Research operations and privacy + +Private research data SHOULD live in an access-controlled system, not the +public repository. The repository MAY contain: + +- redacted hypothesis ledgers; +- evidence summaries; +- scorecards; +- decision records; +- mockups using synthetic data. + +The program MUST define: + +- participant consent; +- retention and deletion; +- access control; +- separation of contact data from technical evidence; +- redaction review; +- handling of regulated or confidential workflows; +- whether interviews may be recorded or transcribed. + +No customer proof, key, credential, policy, patient data, financial record, or +proprietary action payload may enter research artifacts without explicit +authorization and a defined secure location. + +## 12. APIs and artifact contracts + +This program does not create a production runtime API. It defines research artifact +contracts so an executing agent cannot turn vague interest into a product +commitment. + +```ts +type EvidenceLevel = "E0" | "E1" | "E2" | "E3" | "E4" | "E5"; + +interface CommercialEvidence { + readonly evidenceId: string; + readonly level: EvidenceLevel; + readonly sourceType: + | "interview" + | "workflow-observation" + | "integration" + | "security-review" + | "pilot" + | "purchase"; + readonly observedAt: string; + readonly redactedSummary: string; +} + +interface CandidateDecision { + readonly candidateId: string; + readonly decision: + | "select" + | "continue-discovery" + | "defer" + | "reject"; + readonly evidenceFor: ReadonlyArray; + readonly evidenceAgainst: ReadonlyArray; + readonly openCoreReview: "pass" | "fail"; + readonly rationale: string; +} +``` + +Automated agents MAY summarize evidence. They MUST NOT promote its level, +invent buyer statements, or infer commercial commitment not present in the +source. + +## 13. Decision gates + +### Gate A: Problem + +Pass when at least three independent organizations demonstrate the same +operational problem at E2 or stronger. + +### Gate B: Buyer + +Pass when the economic-buyer role, champion, operator, and security reviewer +are identified and at least one buyer invests at E3 or stronger. + +### Gate C: Solution + +Pass when prospects can evaluate a concrete workflow or prototype and agree on +measurable pilot success criteria. + +### Gate D: Deployment + +Pass when the required hosted, on-premises, or hybrid topology and data +boundary are understood well enough to estimate a pilot. + +### Gate E: Open core + +Pass when the candidate adds paid operational value without making local +verification dependent on a commercial service. + +### Gate F: Integration + +Pass when at least two independent AP-SPEC-030 integrations demonstrate the +same operational problem, the repeated-needs register distinguishes it from +one-off adapter work, and the candidate does not require a generic executor or +semantic leakage into shared/core code. + +### Gate G: Commercial + +Pass when at least one qualified prospect progresses toward an E4 paid or +formally sponsored pilot on explicit scope and terms. + +Failure at a gate results in continued discovery, a changed hypothesis, or a +no-build decision—not fabricated certainty. + +## 14. Deliverables + +The product-selection gate produces: + +1. redacted hypothesis ledger; +2. buyer and workflow maps; +3. problem-interview evidence; +4. deployment and security requirement matrix; +5. candidate architecture reviews; +6. solution-test results; +7. candidate scorecard; +8. packaging and willingness-to-pay evidence; +9. one commercial product selection record or a no-build record; +10. a separate implementation PRD only for the selected candidate. + +The PRD MUST state the buyer, problem, success metric, open/paid boundary, +deployment topology, data model, integration surface, and pilot exit criteria. + +## 15. Exit gate + +The product-selection gate passes when one of these outcomes is documented: + +### Selection + +- one recurring problem has E2 observations from at least three independent + organizations; +- at least two independent AP-SPEC-030 integrations demonstrate the same + repeated operational problem; +- the buyer and user roles are distinct where applicable and understood; +- at least one organization supplies E3 or stronger commitment; +- a credible E4 pilot path exists; +- deployment and security requirements are bounded; +- the candidate passes the open-core architecture test; +- evidence supports a value unit and packaging experiment; +- competing candidates are explicitly deferred or rejected; +- a separate product requirements document is ready for review. + +### No-build + +- evidence does not support a paid product yet; +- failed hypotheses and counter-evidence are retained; +- the next discovery test is named; +- no speculative implementation is started. + +Commercial discovery does not end when this gate passes. The gate does not +require a particular paid product, price, ARR target, hosted service, or +enterprise control plane. A disciplined no-build decision is a valid result. diff --git a/docs/specs/0032-reproducible-release-candidate-and-exact-assurance-claim.md b/docs/specs/0032-reproducible-release-candidate-and-exact-assurance-claim.md new file mode 100644 index 0000000..da7c628 --- /dev/null +++ b/docs/specs/0032-reproducible-release-candidate-and-exact-assurance-claim.md @@ -0,0 +1,630 @@ +# AP-SPEC-032: Reproducible release candidate and exact assurance claim + +**Status:** Specified — execution requires approved owner decisions and +separate Phase 7 and Phase 8 pull requests + +**Governs:** Phase 7 and Phase 8 of the +[Post-Milestone 6 Productization and Release Plan](../target-state/POST_MILESTONE_6_PRODUCTIZATION_AND_RELEASE_PLAN.md) + +**Aligned with:** [Post-Milestone-6 Technical and Go-to-Market +Alignment](../plans/POST_MILESTONE_6_TECHNICAL_AND_GO_TO_MARKET_ALIGNMENT.md) + +**Depends on:** AP-SPEC-0011, AP-SPEC-0025, AP-SPEC-0026, the completed +Milestone 6 baseline on `main`, the formal assurance manifest, canonical +fixtures, conformance inventories, benchmark evidence, and the existing +release-check machinery + +**Scope:** One immutable, reproducible release candidate containing the +completed formal and bounded-authorization program, followed by one exact +public assurance claim bound to that candidate's source revision, semantic +identities, artifact digests, evidence, trusted components, and residual +assumptions + +**Normative language:** **MUST**, **MUST NOT**, **SHOULD**, and **MAY** are +requirements on conforming implementations and release operations. + +## 1. Decision + +Auths will execute Phase 7 and Phase 8 as one coordinated assurance program +with two sequential gates: + +```text +completed Milestone 6 revision + | + v +Phase 7: freeze semantics, prepare artifacts, reproduce evidence + | + v +immutable release-candidate tag and digest-bound evidence bundle + | + v +Phase 8: publish the exact claim for that candidate + | + v +fixed review target for Phase 9 +``` + +The phases share one specification because an assurance claim without an exact +artifact subject is not reviewable, while a release candidate without an exact +claim boundary invites unsupported interpretation. + +They remain separate gates. Phase 8 MUST NOT change the tagged source, +semantic identities, generated formal evidence, fixtures, or release +artifacts. If claim preparation discovers missing evidence, semantic drift, or +an inaccurate statement, the candidate is rejected and Phase 7 produces a new +candidate ordinal. The claim MUST NOT be weakened or worded ambiguously to hide +an artifact defect. + +This specification authorizes neither the Phase 10 TypeScript SDK nor any +hosted, production, certification, compliance, SLA, or commercial claim. + +## 2. Current baseline + +The repository already contains: + +- `cargo xtask release-check`, including authoritative CI, package checks, + documentation, wire checks, SBOM generation, checksums, and release evidence; +- `.github/workflows/release.yml`, which runs release checks and preserves + crate archives, formal output, and release evidence; +- `formal/assurance-manifest-v1.toml`, the machine-validated formal claim + inventory; +- qualified Aeneas translation reproduction; +- canonical fixtures, formal vectors, conformance inventories, compliance + evidence, and bounded benchmarks; +- `docs/assurance-model.md` and the formal paper. + +These are implementation inputs, not evidence that Phase 7 or Phase 8 is +already complete. In particular, the current release path: + +- builds after a tag event rather than promoting already verified artifacts; +- emits a custom provenance record rather than signed hosted-build provenance; +- emits CycloneDX 1.5 rather than the alignment's SPDX release baseline; +- preserves workflow artifacts temporarily but does not publish one immutable, + consumer-verifiable assurance bundle; and +- does not yet bind every public claim to the exact release subjects. + +Closing these gaps MUST strengthen the existing checks. It MUST NOT replace or +weaken formal qualification, architecture, compliance, dependency, secret, +fixture, domain, or authoritative CI enforcement. + +## 3. Goals + +This specification MUST produce: + +1. one machine-readable semantic-freeze inventory; +2. one content-addressed release-candidate artifact catalogue; +3. one clean-checkout preparation command; +4. two independent preparation runs with explicitly classified + reproducibility results; +5. one SPDX SBOM per executable or packaged release subject, or one SPDX + document whose relationships cover every subject unambiguously; +6. signed hosted-build provenance meeting the approved Phase 7 supply-chain + target; +7. checksums and consumer verification instructions; +8. one immutable release-candidate tag that promotes, rather than rebuilds, + the verified subjects; +9. one machine-readable exact assurance-claim registry; +10. one human-readable assurance statement generated from or validated against + that registry; and +11. one fixed candidate and claim bundle suitable for independent Phase 9 + review. + +## 4. Non-goals + +Phase 7 and Phase 8 MUST NOT: + +- publish a stable v1 or general-availability compatibility promise; +- implement Phase 10 or Phase 11 product/runtime work from AP-SPEC-027 through + AP-SPEC-030; AP-SPEC-030 recruitment and AP-SPEC-031 discovery MAY proceed + in parallel without changing the RC or making unsupported claims; +- add a new domain, profile, provider, policy language, custody provider, or + hosted service; +- use release closure as permission for semantic refactoring or optimization; +- claim that Lean proves Rust, storage, credentials, networks, or providers + beyond the mechanically established boundary; +- claim that a provider is correct, available, atomic, deterministic, or + exactly-once unless a separately reviewed provider contract establishes the + exact narrower statement; +- describe the candidate as independently audited before Phase 9 completes; +- publish SOC 2, ISO/IEC 27001, CRA certification, zero-trust compliance, + production readiness, SLA, RPO, RTO, or support claims; +- make a hosted service necessary to verify artifacts or Auths proofs; +- rebuild artifacts during tag promotion; +- move, replace, or silently delete an issued release-candidate tag; or +- add compatibility machinery for superseded prelaunch candidates. + +## 5. Owner decisions and entry gate + +Implementation MUST NOT begin until the owner records decisions for the +surfaces affected by the first external release candidate. + +The current decision state is maintained in the +[Phase 7 release owner decision register](../plans/PHASE_7_RELEASE_OWNER_DECISIONS.md). +An unresolved recommendation in that register is not approval. + +| Decision | Recommended default | Required before | +| --- | --- | --- | +| Release license | Keep `MIT OR Apache-2.0` through v1 | Freezing package and release metadata | +| Inbound contribution policy | DCO or CLA selected with counsel | Public contributor recruitment | +| Artifact catalogue | Source, publishable crates, maintained bindings, WASM/native artifacts, assurance bundle | Release workflow implementation | +| Registry publication | Prepare all subjects; publish only to approved registries | Any external package publication | +| Supply-chain target | SLSA Build L2 for the first RC | Provenance contract implementation | +| SBOM baseline | SPDX JSON; CycloneDX MAY be retained as an additional format | Evidence-schema freeze | +| Tag convention | One immutable semver-compatible RC form | Release-tooling implementation | +| Release approvers | At least one named human approver distinct from the build identity | Protected release environment | +| Signing identity | GitHub artifact attestation or an approved Sigstore identity | Artifact promotion | +| Public claim approver | Named technical owner for exact wording and scope | Phase 8 merge | +| Vulnerability and CRA ownership | Named security contact and counsel-reviewed role when external distribution is in scope | Public RC publication | + +The entry revision MUST also satisfy: + +- Milestones 0 through 6 are complete on `main`; +- no open branch contains a required semantic or evidence fix; +- all required checks on the candidate revision are terminal and successful; +- the worktree used for preparation is clean; +- tracked semantic inventories have complete CI ownership; and +- provider and domain behavior remains outside shared/core code. + +## 6. Terminology and identities + +- **Candidate revision:** the exact Git commit proposed for the release + candidate. +- **Preparation run:** a hosted, isolated build of the candidate revision that + produces subjects and evidence without publishing or tagging them. +- **Release subject:** one source archive, package, binary, image, WASM module, + binding archive, evidence bundle, or other artifact identified by digest. +- **Semantic freeze:** the versioned inventory of meanings that the candidate + promises not to change without a new identity or version. +- **Evidence bundle:** the content-addressed collection of manifests, + checksums, SBOMs, provenance, formal evidence, conformance results, + benchmarks, and reproduction instructions. +- **Promotion:** attaching the already prepared subjects to an immutable tag + and approved distribution locations without rebuilding them. +- **Exact assurance claim:** a versioned set of statements whose subjects, + evidence, scope, assumptions, and exclusions are explicit. + +Every manifest MUST use the full Git commit and SHA-256 artifact digests. +Human-readable names and tags are locators, not identities. + +## 7. Phase 7: semantic freeze + +### 7.1 Freeze inventory + +Phase 7 MUST add or generate one machine-readable freeze inventory containing: + +- core protocol versions; +- portable ABI and binding contract versions; +- policy, evaluator, and optimized evaluator semantic IDs; +- canonicalization versions; +- exact-action profile and profile-family versions; +- decision, denial, indeterminate, lifecycle, and reconciliation code sets; +- receipt schema versions and commitment meanings; +- canonical fixture and formal-vector manifest digests; +- bounded-domain and profile-inventory digests; +- persisted reservation, claim, execution, and reconciliation state versions; +- required and executed configuration commitment schemes; +- formal assurance-manifest digest; +- benchmark definition and accepted-baseline digests; and +- every source path or generated artifact that owns the frozen meaning. + +The inventory MUST distinguish: + +- **frozen meaning**, where an incompatible change requires a new semantic + identity or major/pre-release version; +- **frozen bytes**, where the exact digest is part of conformance; and +- **release metadata**, which may change only in a new release candidate. + +The freeze is not a promise to decode or migrate obsolete prelaunch state. +Later incompatible meaning uses a new version and rejects obsolete disposable +state rather than adding compatibility readers or dual paths. + +### 7.2 Drift enforcement + +CI MUST reject: + +- changed frozen bytes without an updated version and review record; +- changed semantics under an existing semantic ID; +- an inventory entry whose source, fixture, test, or manifest does not exist; +- an unregistered decision, denial, indeterminate, transition, or receipt code; +- a profile/evaluator version mismatch; +- a generated artifact that differs from a clean reproduction; and +- a release subject not covered by the release manifest. + +Phase 7 closure MAY fix inventory and evidence defects. It MUST NOT change a +decision, command, transition, provider effect, or receipt meaning merely to +make the freeze easier. A semantic change requires a separately specified and +reviewed pre-RC change before the candidate is prepared. + +## 8. Phase 7: release subjects and evidence bundle + +### 8.1 Required release manifest + +The release manifest MUST contain at least: + +```json +{ + "schema": "auths.release-manifest/1", + "release": { + "tag": "", + "status": "release-candidate" + }, + "source": { + "repository": "auths-dev/auths-proof", + "commit": "" + }, + "semanticFreeze": { + "path": "semantic-freeze.json", + "sha256": "" + }, + "subjects": [ + { + "name": "", + "mediaType": "", + "platform": "", + "size": 0, + "sha256": "" + } + ], + "evidence": { + "spdx": [""], + "provenance": [""], + "formalManifest": "", + "conformance": [""], + "benchmarks": [""] + } +} +``` + +Unknown fields MAY be allowed for compatible metadata extension. Unknown +schema versions, missing subjects, duplicate artifact names, duplicate +semantic identities, relative-path escape, unsupported digest algorithms, and +digest mismatches MUST fail closed. + +### 8.2 Evidence bundle contents + +The evidence bundle MUST include: + +- the release manifest and semantic-freeze inventory; +- `SHA256SUMS` covering every included file other than an explicitly specified + detached signature over the checksum manifest; +- SPDX SBOMs with package relationships, licenses, versions, and checksums; +- signed hosted-build provenance whose subjects exactly equal the release + manifest subjects; +- source archive and exact lockfiles/toolchain records; +- formal assurance manifest, theorem inventory, axioms, external models, + source-closure report, and qualification results; +- byte-identical Aeneas reproduction evidence; +- canonical fixture, formal-vector, conformance, architecture, compliance, + and domain-inventory reports; +- reference-versus-extracted and reference-versus-optimized differential + results; +- exact benchmark inputs, environment, reports, and acceptance records; +- native/binding compatibility and package dry-run results; +- secret-scan and dependency-policy results; +- release notes that say `release candidate` and enumerate unsupported claims; + and +- offline consumer verification instructions. + +Release evidence required to trust open artifacts MUST remain public and MUST +NOT require a commercial account. + +### 8.3 Reproducibility classes + +Every subject MUST declare one class: + +| Class | Requirement | +| --- | --- | +| `byte-identical` | Two isolated preparation runs produce identical bytes and digest. | +| `deterministic-evidence` | Regenerated semantic/formal/fixture evidence is byte-identical after normalized paths and approved deterministic metadata. | +| `platform-reproducible` | The declared platform and toolchain reproduce the artifact; the official hosted-build digest remains the distribution identity. | +| `provenance-only` | Bit reproduction is not established; signed provenance identifies the official artifact and the release makes no reproducibility claim for it. | + +Source manifests, semantic inventories, canonical fixtures, formal vectors, +generated Lean, assurance registries, checksums, and deterministic reports MUST +be `byte-identical` or `deterministic-evidence`. + +An artifact MUST NOT be called reproducible merely because it has provenance. +Any `provenance-only` subject requires a named limitation in the release notes +and Phase 8 claim registry. + +## 9. Phase 7: prepare and promote + +### 9.1 Preparation + +One canonical command MUST prepare the complete candidate from a clean +checkout. It MAY orchestrate existing `xtask` commands, but it MUST not require +manual edits between steps. + +Preparation MUST: + +1. verify the exact candidate commit and clean tree; +2. run the complete required CI and release gates; +3. rebuild all deterministic and generated evidence; +4. package every approved subject; +5. generate SBOMs, provenance subjects, checksums, and the release manifest; +6. validate the evidence graph and semantic-freeze inventory; +7. run a second isolated reproduction; +8. compare results by declared reproducibility class; +9. store the approved subjects in content-addressed staging; and +10. emit the manifest digest for human approval. + +The second run MUST start from a fresh checkout and empty build-output +directories. Shared caches MAY accelerate dependency retrieval but MUST NOT be +accepted as release subjects or hide missing declared inputs. + +### 9.2 Promotion + +After all required checks are terminal and successful, the authorized owner +creates the immutable RC tag at the candidate commit. Promotion MUST: + +- verify that the tag, candidate commit, workspace version, semantic freeze, + staged release manifest, and approval agree; +- retrieve every subject by recorded digest; +- verify checksums, SBOM subject coverage, and signed provenance; +- attach or publish the exact staged bytes; +- attach consumer-verifiable attestations; +- mark the GitHub release and registry versions as prerelease where supported; +- publish the evidence bundle and verification instructions; and +- prove that no build or evidence-generation step ran during promotion. + +The current tag-triggered release workflow MUST be changed or wrapped so it +promotes prepared artifacts rather than creating new release bytes. + +### 9.3 Failure and withdrawal + +Before promotion, any mismatch aborts the candidate and publishes nothing. + +After promotion: + +- the tag MUST NOT move; +- the artifacts and evidence MUST NOT be overwritten; +- a defective candidate is marked withdrawn with a bounded reason and security + guidance; +- fixes use a new commit and new RC ordinal; and +- a withdrawal MUST NOT be represented as successful Phase 7 completion. + +## 10. Phase 7 exit gate + +Phase 7 is complete only when: + +- the owner decisions in Section 5 are recorded; +- one clean `main` revision contains the completed Milestone 6 program and all + release-contract changes; +- every frozen identity and byte set is inventoried and drift-enforced; +- two isolated preparation runs satisfy every declared reproducibility class; +- every release subject is checksum-, SBOM-, and provenance-covered; +- provenance meets the approved supply-chain target; +- consumer verification succeeds without repository write access or an Auths + service; +- promotion publishes the exact prepared bytes and performs no rebuild; +- the immutable tag resolves to the recorded candidate commit; +- the release is clearly labeled as a candidate, not stable v1; and +- the evidence bundle contains the internal assurance manifest needed by + Phase 8. + +## 11. Phase 8: exact assurance-claim contract + +### 11.1 Claim layers + +The claim registry MUST preserve these distinct layers: + +```text +rich Lean authorization semantics + | + v +qualified production Rust refinement + | + v +bounded representation and state obligations + | + v +tested storage, credential, and execution components + | + v +trusted nondeterministic provider boundary + | + v +observed and receipted provider outcome +``` + +A stronger layer MUST NOT be inferred from evidence for a weaker or different +layer. In particular: + +- a Lean theorem is not automatically a claim about shipping Rust; +- a mechanically translated pure Rust function is not the networked runtime; +- a Kani harness proves only its bounded model and assumptions; +- a passing integration test is not a theorem; +- provider acceptance is not observed success; +- observed success is not provider atomicity or global exactly-once behavior; +- a signed artifact is not necessarily secure; and +- Phase 8 has no independent-audit evidence until Phase 9 completes. + +### 11.2 Claim registry + +Every public security claim MUST exist in one machine-readable registry entry +with: + +```json +{ + "claimId": "AUTHS-RC-", + "text": "", + "subjects": ["sha256:"], + "classification": "theorem|refinement|bounded-model|test|audit|assumption|exclusion", + "evidence": [""], + "trustedComponents": [""], + "residualAssumptions": [""], + "exclusions": [""], + "compatibility": "" +} +``` + +The registry MUST reject: + +- prose claims without artifact subjects; +- evidence that is absent from or digest-inconsistent with the RC bundle; +- theorem claims without exact declarations and premises; +- refinement claims without production source closure and qualification + evidence; +- bounded-model claims without limits and representation assumptions; +- test claims without exact suite, revision, and result; +- `audit` classification before a scoped independent report exists; +- empty trusted-component or residual-assumption fields when the evidence has + such dependencies; +- provider or production claims that exceed recorded evidence; and +- compatibility language broader than the frozen versions. + +### 11.3 Human-readable assurance statement + +Phase 8 MUST publish one concise assurance statement generated from or +validated against the claim registry. It MUST: + +- name the RC tag, commit, release-manifest digest, and claim-registry digest; +- distinguish proved, mechanically connected, model-checked, tested, trusted, + and excluded surfaces; +- list foundational axioms, external models, toolchains, and runtime trust; +- identify provider behavior outside the proof; +- distinguish authorization, durable execution authorization, provider + acceptance, unknown outcome, reconciliation, and observed postcondition; +- state that the artifact is a release candidate and has not yet completed + Phase 9 independent review; +- state version and compatibility limits; and +- link directly to offline verification instructions and evidence subjects. + +The paper, release notes, `docs/assurance-model.md`, security documentation, +and later website or sales material MUST use this registry as the source of +claim truth. Separate repositories MUST consume the published claim artifact +or pinned release metadata; they MUST NOT use mutable sibling paths. + +### 11.4 Claim synchronization + +CI MUST inventory public security-claim locations and fail when: + +- public wording has no registry entry; +- wording changes without a claim-registry change; +- a claim references a different RC, semantic identity, or artifact digest; +- excluded provider behavior is described as proved; +- `audited`, `certified`, `production-ready`, `compliant`, or equivalent + language appears without the separately required evidence; or +- generated claim documentation is stale. + +Guidance and explanatory prose MAY summarize claims, but it MUST preserve the +same scope and MUST NOT omit limitations in a way that materially strengthens +the statement. + +## 12. Phase 8 exit gate + +Phase 8 is complete only when: + +- Phase 7 completed for one immutable, non-withdrawn RC; +- every public security claim maps to exact RC subjects and evidence; +- every theorem-backed claim names its declaration, premises, source closure, + and residual assumptions; +- bounded-model and test-backed claims state their limits; +- trusted runtime, build, storage, credential, operator, and provider + components are explicit; +- authorization, execution, acceptance, observation, and reconciliation are + not collapsed into one verdict; +- public-claim synchronization passes; +- the named technical owner approves the exact wording; +- no statement implies independent review has already completed; and +- the claim bundle provides the fixed scope submitted to Phase 9 reviewers. + +## 13. Required evidence and adversarial tests + +Implementation MUST add tests for: + +- dirty-tree and wrong-commit preparation rejection; +- tag, workspace-version, and candidate-commit mismatch; +- missing, duplicate, oversized, malformed, or digest-mismatched subjects; +- incomplete SPDX coverage and license metadata; +- provenance with a wrong repository, workflow, commit, builder, or subject; +- promotion attempting to rebuild or mutate a subject; +- deterministic evidence differing between isolated runs; +- a `provenance-only` artifact presented as bit-reproducible; +- semantic changes under unchanged IDs; +- stale generated formal, fixture, conformance, benchmark, or claim evidence; +- a public claim with no registry entry; +- theorem, refinement, Kani, test, and provider-scope overclaims; +- an audit claim with no Phase 9 report; +- missing assumptions or trusted components; +- provider acceptance presented as observed success; +- withdrawn RC verification; and +- offline verification from a clean environment. + +Tests MUST mutate evidence and subjects, not only exercise valid generation. +The implementation MUST prove that a changed byte, digest, source closure, +semantic ID, or claim reference causes a terminal failure. + +## 14. Required pull-request and release boundaries + +This specification is one semantic contract. Its implementation is not one +large pull request. + +The minimum boundaries are: + +1. **Decision and specification PR.** Record owner decisions, this + specification, schemas, and the execution plan. No release implementation. +2. **Semantic-freeze PR.** Add the freeze inventory and drift enforcement. + No artifact publication or public claim changes. +3. **Release-evidence PR.** Add SPDX, signed provenance subjects, release + manifest, reproducibility classification, and adversarial validation. +4. **Prepare/promote PR.** Implement isolated preparation, second-run + comparison, protected approval, immutable tag verification, and no-rebuild + promotion. +5. **Candidate-closure PR.** Apply only evidence-backed fixes required for the + candidate, regenerate committed deterministic evidence, and establish the + final candidate revision. No tag is created until its required checks pass. +6. **Phase 7 promotion event.** Create and promote the immutable RC tag. This + changes external release state but does not change repository source. +7. **Exact-claim PR.** Add the RC-bound claim registry, public assurance + statement, and synchronization enforcement. It MUST NOT modify the tagged + semantics or release subjects. + +If the exact-claim PR exposes a Phase 7 defect, stop it, fix the defect through +a new candidate-closure PR, issue a new RC ordinal, and rebind the claim. Do +not combine remediation and claim publication in one review. + +Each implementation PR MUST describe its affected claims, frozen identities, +generated artifacts, validation, exclusions, and rollback or withdrawal +behavior. Provider/domain behavior MUST remain profile- or domain-owned. + +## 15. Delivery order + +1. Record the owner decisions in Section 5. +2. Freeze the semantic and artifact schemas. +3. Implement and validate the semantic-freeze inventory. +4. Upgrade release evidence to the approved SBOM and provenance contract. +5. Implement clean preparation and no-rebuild promotion. +6. Run two isolated preparations and close reproducibility gaps. +7. Merge the final candidate revision after all checks pass. +8. Promote the immutable RC tag and publish its evidence bundle. +9. Build the exact claim registry against those immutable subjects. +10. Publish and synchronize the human-readable assurance statement. +11. Submit the fixed candidate and claim bundle to Phase 9 independent review. + +## 16. Completion and handoff + +This specification is complete only when both phase exit gates pass. + +Completion means: + +- a reviewer can retrieve the RC by tag and verify its exact source and + artifact digests; +- a clean environment can reproduce every artifact according to its declared + class and can verify official provenance for all subjects; +- semantic meaning cannot drift under the candidate's frozen identities; +- every public security statement has exact evidence, assumptions, exclusions, + and release subjects; +- the same claim boundary is usable by release notes, documentation, future + websites, and Phase 9 review without marketing reinterpretation; and +- AP-SPEC-027, AP-SPEC-028, and the provider-neutral implementation portion of + AP-SPEC-029 remain blocked until AP-SPEC-033 permits an explicitly labeled + Phase 10 developer preview. + +The next technical program after completion is Phase 9 independent review. It +is not SDK implementation by default; reviewer engagement, findings, +remediation, retest, and the no-critical-findings gate still apply. + +AP-SPEC-030 recruitment and AP-SPEC-031 problem, buyer, deployment, and +willingness-to-pay discovery may continue alongside this work within their +non-production and evidence-handling boundaries. diff --git a/docs/specs/0033-independent-review-and-remediation-gate.md b/docs/specs/0033-independent-review-and-remediation-gate.md new file mode 100644 index 0000000..c362ae0 --- /dev/null +++ b/docs/specs/0033-independent-review-and-remediation-gate.md @@ -0,0 +1,583 @@ +# AP-SPEC-033: Independent review and remediation gate + +**Status:** Specified — Phase 9 execution begins only after AP-SPEC-032 has +completed both exit gates + +**Governs:** Phase 9 of the +[Post-Milestone 6 Productization and Release Plan](../target-state/POST_MILESTONE_6_PRODUCTIZATION_AND_RELEASE_PLAN.md) + +**Aligned with:** [Post-Milestone-6 Technical and Go-to-Market +Alignment](../plans/POST_MILESTONE_6_TECHNICAL_AND_GO_TO_MARKET_ALIGNMENT.md) + +**Depends on:** [AP-SPEC-032](0032-reproducible-release-candidate-and-exact-assurance-claim.md), +one immutable and non-withdrawn release candidate, its exact assurance-claim +bundle, and approved review ownership, budget, disclosure, and severity policy + +**Scope:** Independent formal-methods, Rust/protocol-security, and stateful- +execution review of one fixed release candidate and claim bundle; structured +finding intake; remediation and regression evidence; independent retest; and +the exact gate that permits a labeled Phase 10 developer preview + +**Normative language:** **MUST**, **MUST NOT**, **SHOULD**, and **MAY** are +requirements on review operations, repository changes, evidence, and claims. + +## 1. Decision + +Auths will submit the exact Phase 7 release candidate and Phase 8 assurance +claim to independent specialists before beginning the Phase 10 developer +surface. + +Phase 9 is not a request for a general endorsement. It is a bounded attempt to +find defects in exact artifacts and claims: + +```text +immutable RC + exact claim bundle + | + v ++--------------- independent review tracks ----------------+ +| formal methods | Rust/protocol security | stateful effects | ++------------------------|-----------------------------------+ + v + structured findings registry + | + +----------+-----------+ + | | + v v + claim correction code/evidence fix + | | + +----------+-----------+ + v + regression evidence + retest + | + v + Phase 9 gate report +``` + +The reviewed source revision, release subjects, semantic identities, assurance +claims, reviewer scope, findings, remediation, and retest evidence MUST remain +connected by immutable identifiers and digests. + +If remediation changes a frozen byte, semantic identity, release subject, or +claim subject, the old candidate cannot silently inherit the fix. AP-SPEC-032 +MUST produce a new RC ordinal and rebound claim bundle before affected review +can close. + +## 2. Bounded outcome + +Successful Phase 9 completion supports only this statement: + +> Independent reviewers assessed the named release candidate and assurance +> claims within their recorded scopes; every finding has a recorded +> disposition and owner; no critical finding remains unresolved; and the +> remediation identified as complete has passed independent retest. + +It does not establish: + +- that Auths is defect-free; +- that unreviewed revisions inherit the result; +- that all reviewers assessed every subsystem; +- that an external provider is correct, available, atomic, or deterministic; +- that a future Phase 10 SDK or Phase 11 runtime was reviewed; +- that Auths is production-ready, certified, compliant, or covered by an SLA; +- that a private report may be summarized as an unqualified public audit; or +- that medium, low, informational, accepted, or out-of-scope risks do not + exist. + +## 3. Entry gate and owner decisions + +Phase 9 MUST NOT begin until: + +- AP-SPEC-032 Phase 7 and Phase 8 are complete; +- the immutable RC is retrievable and not withdrawn; +- the release manifest, semantic-freeze inventory, claim registry, assurance + statement, and evidence-bundle digests agree; +- consumer verification succeeds from a clean environment; +- the owner names a review coordinator who is not the sole author or approver + of the in-scope implementation; +- review budget and contracting authority are recorded; +- confidentiality, coordinated-disclosure, report-retention, and publication + rules are recorded; +- the severity and risk-acceptance policy in this specification is approved; +- the required reviewer competencies and conflict rules are approved; and +- each track has an agreed statement of work and completion criteria. + +The owner MAY use one firm for multiple tracks only when the firm assigns +reviewers with the required distinct competencies and reports scope and +conflicts per track. Cost or scheduling pressure MUST NOT silently remove a +track. + +## 4. Reviewer independence and competence + +Every lead reviewer MUST: + +- be organizationally independent from the Auths implementation and release + approval; +- have no authorship responsibility for the in-scope production code or proof + artifacts; +- disclose financial, employment, contribution, and advisory conflicts; +- be free to report adverse findings without payment or publication being + conditioned on a favorable result; +- identify the exact portions personally reviewed and work delegated to other + reviewers; and +- authenticate the final report or deliver it through an integrity-protected + channel. + +Paid review is independent review when these conditions hold. Independence +does not require anonymity or unpaid work. + +The formal-methods lead MUST be able to review Lean theorem statements, +translation/refinement arguments, axioms, representation boundaries, and +qualification evidence. + +The Rust/protocol-security lead MUST be able to review Rust memory and type +safety, cryptographic protocol use, bounded parsing, canonicalization, +authorization semantics, replay controls, configuration binding, dependency +and secret handling, and release integrity. + +The stateful-execution lead MUST be able to review transactional persistence, +concurrency, crash boundaries, claims and reservations, credential ordering, +nondeterministic provider delivery, ambiguous outcomes, reconciliation, and +recovery. + +## 5. Review target and packet + +### 5.1 Scope manifest + +One machine-readable scope manifest MUST bind: + +- RC tag and full commit; +- release-manifest, semantic-freeze, evidence-bundle, and claim-registry + digests; +- release subjects assigned to each track; +- source paths, generated artifacts, theorem declarations, tests, fixtures, + and claims assigned to each track; +- explicitly excluded surfaces and the reason for each exclusion; +- approved reviewer identities and conflict declarations; +- review start date and packet version; and +- required deliverables and retest expectations. + +A source or claim may appear in multiple tracks. Shared coverage does not make +ownership ambiguous: each track records what property it reviewed. + +### 5.2 Review packet + +The packet MUST include: + +- offline artifact and evidence verification instructions; +- repository build, test, formal-reproduction, and conformance instructions; +- architecture and trust-boundary documentation; +- threat models and known residual assumptions; +- formal assurance manifest, source-closure report, qualification evidence, + axioms, and external models; +- protocol, profile, evaluator, canonicalization, decision-code, and receipt + inventories; +- state-transition, credential, replay, reconciliation, and recovery models; +- dependency, SBOM, provenance, benchmark, architecture, and compliance + evidence; +- prior relevant review findings and their status; and +- a protected channel for suspected vulnerabilities. + +The packet MUST be reproducible from recorded release subjects. Reviewer-only +access instructions MAY be separate, but private material MUST NOT silently +change the public review target. + +## 6. Required review tracks + +### 6.1 Formal methods and assurance boundary + +This track MUST assess: + +- whether public theorem claims match exact Lean declarations and premises; +- whether rich authorization, attenuation, and bounded-policy statements + express the intended security properties; +- Aeneas and Charon qualification, version pinning, generated artifacts, and + source-closure claims; +- representation mappings between production Rust and Lean values; +- transitive axioms, external models, trusted code, and unresolved `sorry` or + equivalent escape hatches; +- Kani claims and their bounds, harness assumptions, and relationship to the + general Lean claims; +- whether differential, mutation, property, fuzz, conformance, and integration + evidence are described at the strength they actually provide; +- whether authorization, execution, provider acceptance, observation, and + reconciliation remain distinct; and +- every Phase 8 claim classified as theorem or refinement. + +The reviewer MUST attempt to construct counterexamples at representation and +trust boundaries, not merely confirm that proof commands succeed. + +### 6.2 Rust, cryptography, and protocol security + +This track MUST assess: + +- canonical encoding and rejection of alternate, trailing, over-depth, + oversized, or unknown-version inputs; +- signature descriptors, domain separation, algorithm agility, key handling, + and verification-method binding; +- delegation attenuation, time, audience, resource, permission, budget, and + depth enforcement; +- required-versus-executed policy and evaluator configuration equality; +- sealed verified-command construction and inability to forge it through + public APIs; +- replay, commitment, receipt, and stable-code integrity; +- allocation and deterministic-work bounds before expensive processing; +- secret lifetime, redaction, credential ordering, test keys, and logging; +- use of `unsafe`, build scripts, native dependencies, and dependency-policy + exceptions; +- denial and indeterminate behavior at every public boundary; and +- release subject, SBOM, checksum, provenance, and claim synchronization. + +Cryptographic review MUST distinguish correct use of reviewed primitives from +proof of the primitives themselves. + +### 6.3 Stateful authorization and exact-effect execution + +This track reviews the stateful and provider-facing behavior present in the RC, +not the future Phase 11 production runtime. + +It MUST assess: + +- atomic replay and reservation behavior; +- capacity conservation and concurrent final-unit races; +- durable decision, claim, execution-intent, delivery, observation, and + reconciliation transitions; +- denial and indeterminate persistence; +- credential acquisition only after all required authorization and claim + gates; +- exact equality between verified commands and outbound provider commands; +- crashes before credentials, before delivery, after possible delivery, and + after provider response; +- ambiguous provider outcomes and prohibition on blind duplicate execution; +- reconciliation freshness, revocation, retry, and terminal-state behavior; +- isolation level, compare-and-swap, transaction, lock, and fencing + assumptions; +- receipt truth across authorization, provider acceptance, observation, and + recovery; and +- domain ownership of provider, credential, lifecycle, and receipt semantics. + +Findings about capabilities absent from the RC MUST be recorded as future +requirements or exclusions, not misreported as defects in an implemented +surface. + +### 6.4 Cross-track claim review + +Each track MUST identify claims it supports, contradicts, narrows, or cannot +assess. The review coordinator MUST reconcile disagreements without merging +different evidence classes into one verdict. + +At least one reviewer outside the original Phase 8 claim authorship MUST read +the complete human-readable assurance statement for misleading composition, +not only validate individual registry entries. + +## 7. Reviewer experience and status view + +The repository SHOULD provide one read-only command that verifies the packet +and renders review status without editing findings: + +```text ++------------------------------------------------------------------+ +| Auths Phase 9 review · auths-proof-v1.0.0-rc.N | ++------------------------------------------------------------------+ +| Packet verified · commit 8f62... · manifest 14ac... | +| Formal complete · findings 0C 1H 3M 2L | +| Protocol retest · findings 0C 0H 2M 4L | +| Stateful active · findings 1C 2H 1M 0L | ++------------------------------------------------------------------+ +| Gate BLOCKED · unresolved critical STATE-004 | +| Claims 2 narrowed · 1 suspended | ++------------------------------------------------------------------+ +``` + +The view MUST be generated from validated artifacts. Color, labels, or a +summary count MUST NOT override the structured gate result. + +## 8. Finding and gate artifact APIs + +### 8.1 Finding schema + +Every finding MUST record at least: + +```yaml +schema: auths.review-finding/1 +finding_id: PROTOCOL-007 +track: rust-protocol-security +severity: high +title: bounded non-sensitive title +status: open +rc_tag: auths-proof-v1.0.0-rc.N +subject_digests: + - sha256:... +source_locations: + - product/example/src/lib.rs +affected_claim_ids: + - AUTHS-RC-example +security_property: exact property affected +preconditions: bounded triggering conditions +impact: bounded impact statement +reproduction_evidence: reviewer-private-or-public-reference +owner: repository-owner-id +disclosure: coordinated +``` + +The public repository MAY contain a redacted security-safe projection while +remediation is pending. The canonical private finding MUST retain the exact +reproduction and affected subjects under approved access controls. + +### 8.2 Severity + +Severity MUST be based on reachable impact, authority or secret exposure, +integrity loss, exploit prerequisites, affected deployment, and evidence—not +reputation or remediation cost. + +| Severity | Required handling | +| --- | --- | +| Critical | Blocks Phase 9 exit and all affected previews; must be remediated and independently retested. | +| High | Blocks the affected claim, surface, and production release; must be remediated and retested or receive bounded owner acceptance with a deadline and explicit release block. | +| Medium | Requires an owner, disposition, regression plan where applicable, and target gate. | +| Low | Requires a recorded disposition and rationale. | +| Informational | Records a limitation, hardening opportunity, or documentation correction without implying a vulnerability. | + +A critical finding MUST NOT be risk-accepted to close Phase 9. Severity changes +require reviewer rationale and retain the previous classification. + +### 8.3 Status and disposition + +Allowed statuses are: + +- `open`; +- `triaged`; +- `remediation-planned`; +- `remediated-awaiting-retest`; +- `retest-passed`; +- `retest-failed`; +- `risk-accepted`; +- `duplicate`; or +- `not-applicable`. + +`duplicate` and `not-applicable` require reviewer-visible rationale. Repository +owners MUST NOT unilaterally mark an adverse finding closed. + +### 8.4 Gate report + +The machine-readable gate result MUST expose at least: + +```ts +type ReviewSeverity = + | "critical" + | "high" + | "medium" + | "low" + | "informational"; + +interface Phase9GateReport { + readonly schema: "auths.phase9-gate/1"; + readonly rcTag: string; + readonly rcCommit: string; + readonly reviewPacketDigest: string; + readonly claimRegistryDigest: string; + readonly trackReportDigests: ReadonlyArray; + readonly decision: "blocked" | "phase10-preview-permitted"; + readonly unresolvedBySeverity: Readonly>; + readonly blockedSurfaceIds: ReadonlyArray; + readonly suspendedClaimIds: ReadonlyArray; + readonly knownRiskRegisterDigest: string; + readonly decidedAt: string; + readonly ownerApprovalId?: string; +} +``` + +The gate calculator MUST be pure over validated registry and report inputs. +`ownerApprovalId` is required only for `phase10-preview-permitted`; its presence +cannot override a critical finding, missing track, stale subject, failed +retest, or active release block. + +## 9. Remediation and candidate replacement + +Every confirmed security finding MUST produce at least one durable regression +or assurance artifact appropriate to its layer: + +- Lean theorem or corrected statement; +- Aeneas/Charon qualification or source-closure obligation; +- Kani harness; +- canonical negative fixture; +- mutation, property, fuzz, conformance, or integration test; +- architecture or compliance rule; +- operational control and exercise; or +- explicit residual assumption or exclusion in the claim registry. + +Documentation alone is sufficient only when the implementation is correct and +the defect is exclusively an inaccurate or ambiguous claim. + +Remediation is classified as: + +1. **Claim-only:** no release subject or semantic identity changes. Publish a + new claim-bundle version, preserve the superseded wording, and retest the + claim. +2. **Implementation without semantic change:** source or artifact bytes change + while meaning remains compatible. Produce a new RC ordinal through + AP-SPEC-032 and retest affected implementation and claims. +3. **Semantic correction:** protocol, policy, evaluator, action, receipt, + persisted-state, or code meaning changes. Assign new semantic identity or + version, produce migration and compatibility evidence where applicable, + issue a new RC ordinal, and rerun every affected review obligation. + +No report or pull request may describe a superseded RC as remediated. The +finding record MUST name the candidate that contains the fix and the candidate +against which retest passed. + +## 10. Retest + +Independent retest MUST: + +- be performed by the original reviewer or another qualified independent + reviewer approved for the track; +- reproduce the original condition against the original candidate where safe; +- verify the new regression fails on the defective behavior and passes on the + remediation; +- verify the fix did not broaden authority or weaken an adjacent invariant; +- check every affected claim and release subject; +- record exact commit, RC tag, semantic identities, commands, and evidence; +- state what was not retested; and +- authenticate the retest result. + +A passing repository test run is necessary evidence where applicable but is +not an independent retest by itself. + +## 11. Restricted Phase 9 preview + +Phase 9 MAY support AP-SPEC-030 recruitment and a restricted preview only when: + +- AP-SPEC-032 is complete; +- the preview is labeled non-production and pre-audit; +- effects are synthetic, local, sandboxed, read-only, draft, or demonstrably + reversible; +- no production credential, regulated data, financial mutation, + infrastructure mutation, or irreversible external effect is in scope; +- the participant receives the exact assurance exclusions and known-finding + notice appropriate to the preview; +- the preview uses pinned RC or review artifacts; +- collection of evidence is local, opt-in, and redacted; and +- any reviewer or owner can suspend the affected preview after a finding. + +Preview use does not satisfy a review obligation and MUST NOT be cited as +independent security evidence. + +## 12. Security, confidentiality, and disclosure + +- Vulnerability reports MUST use the approved protected channel. +- Public artifacts MUST not expose an unremediated exploit recipe before the + coordinated-disclosure decision. +- Confidentiality MUST NOT be used to hide review scope, reviewer identity, + unresolved severity counts, claim withdrawals, or the existence of a + release-blocking condition from authorized decision-makers. +- Reports and evidence MUST follow recorded retention, access, backup, + deletion, and legal-disclosure rules. +- Reviewer access MUST be least-privilege, time-bounded, and revoked at the end + of the engagement. +- Test credentials and keys MUST be synthetic and unmistakably non-production. +- A reviewer MUST be able to report coercion, conflict, or scope interference + directly to the owner. + +Public disclosure follows the approved coordinated-disclosure policy. A +public summary MUST name exact reviewed revisions and scopes and MUST preserve +all material limitations. + +## 13. Required artifacts and validation + +Phase 9 MUST produce: + +1. approved review charter and owner decisions; +2. digest-bound scope manifest and reproducible review packet; +3. reviewer competence and conflict declarations; +4. one report per required track; +5. validated canonical findings registry; +6. claim-impact and remediation map; +7. regression evidence for every confirmed security finding; +8. independent retest records for every finding represented as remediated; +9. current known-risk and release-block register; +10. public security-safe summary; and +11. machine-readable and human-readable Phase 9 gate reports. + +Validation MUST reject: + +- a report bound to the wrong commit, RC, subject, scope, or claim bundle; +- missing reviewer independence or conflict declarations; +- findings with unknown severities, statuses, owners, or affected subjects; +- a severity downgrade without retained rationale; +- critical risk acceptance; +- a remediated status without regression and independent retest evidence; +- a retest that targets a different fix than the recorded remediation; +- a withdrawn or superseded candidate presented as current; +- a claim that remains public after its supporting evidence was invalidated; +- a gate report that omits private unresolved finding counts; and +- Phase 10 permission while the applicable release block remains active. + +The gate calculation MUST be deterministic and tested with mutation and +boundary cases. + +## 14. Pull-request and external-event boundaries + +Phase 9 is not one pull request. The minimum boundaries are: + +1. **Review-contract PR.** Add this specification, schemas, gate calculator, + and validation tests. +2. **Packet PR.** Add the scope manifest and reproducible packet references for + the exact AP-SPEC-032 candidate. +3. **Review engagement.** External reviewers receive the fixed packet. This is + an external event and changes no repository semantics. +4. **Finding-intake PRs.** Add security-safe finding projections, claim blocks, + and regression obligations without combining unrelated remediation. +5. **Remediation PRs.** Fix bounded findings with their regression evidence. +6. **Replacement-RC events.** When required, execute AP-SPEC-032 for a new RC + and claim bundle. +7. **Retest records.** Add or bind authenticated independent retest evidence. +8. **Gate-closure PR.** Publish the final registry projection, known-risk + register, claim state, and gate report without implementation changes. + +Finding confidentiality MAY require private coordination before public PRs. +It does not permit skipping the repository evidence and release gates. + +## 15. Phase 9 exit gate + +Phase 9 is complete only when: + +- all three required review tracks completed their recorded scopes; +- every report is bound to the current non-withdrawn RC and claim bundle; +- every finding has severity, affected subjects and claims, owner, disposition, + and disclosure state; +- no critical finding remains unresolved; +- every critical remediation passed independent retest; +- each unresolved high finding has explicit bounded owner acceptance, deadline, + affected-claim suspension, and release-blocking status; +- every finding represented as remediated has durable regression evidence and + independent retest; +- superseded candidates and claims are visibly superseded; +- the public assurance statement reflects every material narrowing, + assumption, exclusion, and unresolved risk; +- the known-risk register and gate calculation validate; +- the owner approves only an explicitly labeled Phase 10 developer preview; + and +- the gate report names what must still occur before production, public v1, + certification, compliance, or SLA claims. + +Passing Phase 9 permits AP-SPEC-027 and the local, reversible AP-SPEC-028 work. +It does not permit consequential customer effects, a production runtime, or +unqualified public security claims. + +## 16. Handoff + +After Phase 9: + +- AP-SPEC-027 may implement the Phase 10 TypeScript developer preview; +- AP-SPEC-028 may implement the Phase 10 local and reversible MCP reference + vertical; +- AP-SPEC-029 may implement its provider-neutral Phase 10 contracts; +- AP-SPEC-030 may widen from recruitment into measured restricted + integrations; and +- AP-SPEC-031 discovery continues, but product selection remains evidence- + gated. + +Deployable custody, consequential customer operation, runtime chaos and +recovery, deployment penetration testing, profile conformance qualification, +flagship production operation, and public v1 remain governed by Phases 11 +through 15 and their separate execution plans.