From a062c47c4c103478110b7aaf4cc812e79f8e72c7 Mon Sep 17 00:00:00 2001 From: bordumb Date: Fri, 31 Jul 2026 17:39:33 +0200 Subject: [PATCH] docs: record phase 7 release decisions Auths-Id: did:keri:EMN-WRXNAkLfavKsaFHS0ehP7eB1s8a1alktBJoDhI7b Auths-Device: did:keri:EAswoxxXY6-kXqYcc3mUngY8GOiwhDwXxFfjWXzCvuW6 Auths-Anchor-Seq: 1 --- docs/plans/PHASE_7_OWNER_DECISION_GUIDE.md | 335 ++++++++++++++++++ docs/plans/PHASE_7_RELEASE_OWNER_DECISIONS.md | 238 +++++++++++-- docs/plans/PHASE_7_RELEASE_READINESS_AUDIT.md | 24 +- .../0027-product-grade-typescript-sdk.md | 6 +- ...ase-candidate-and-exact-assurance-claim.md | 35 +- 5 files changed, 600 insertions(+), 38 deletions(-) create mode 100644 docs/plans/PHASE_7_OWNER_DECISION_GUIDE.md diff --git a/docs/plans/PHASE_7_OWNER_DECISION_GUIDE.md b/docs/plans/PHASE_7_OWNER_DECISION_GUIDE.md new file mode 100644 index 0000000..cdf21a4 --- /dev/null +++ b/docs/plans/PHASE_7_OWNER_DECISION_GUIDE.md @@ -0,0 +1,335 @@ +# Phase 7 owner decision guide + +## Purpose + +This guide explains the choices in the +[Phase 7 owner decision register](PHASE_7_RELEASE_OWNER_DECISIONS.md). It does +not make or approve them. + +The recommendations optimize for a first independently reviewable RC, not a +general-availability launch. Legal, regulatory, contribution-rights, and +trademark questions require qualified advice where applicable. + +## Decision bundles + +The 11 decisions fall into four bundles: + +| Bundle | Decisions | Why they belong together | +| --- | --- | --- | +| Legal and contribution boundary | `P7-OD-001`, `P7-OD-002`, `P7-OD-011` | Determines distribution rights, inbound rights, vulnerability ownership, and external-release obligations | +| Artifact and distribution boundary | `P7-OD-003`, `P7-OD-004`, `P7-OD-007` | Determines what is built, where it may be published, and how the immutable candidate is named | +| Supply-chain evidence | `P7-OD-005`, `P7-OD-006`, `P7-OD-009` | Determines provenance strength, SBOM representation, signing identity, and consumer verification | +| Human authority | `P7-OD-008`, `P7-OD-010` | Separates build identity from release approval and names the owner of public claim wording | + +An owner may decide bundles separately. Implementation still remains blocked +until every decision needed by the affected release surface is approved. + +## `P7-OD-001`: release license + +### Current fact + +All workspace packages currently declare `MIT OR Apache-2.0`, and both license +texts are present. + +### Options + +1. Keep `MIT OR Apache-2.0` through v1. +2. Move future release artifacts to Apache-2.0 only after rights and + contribution review. +3. Defer external distribution and prepare a private candidate while counsel + evaluates a different boundary. + +### Recommended default + +Keep the existing dual license through v1. It avoids an unnecessary +relicensing event and preserves the repository's current open-source boundary. + +### Owner must state + +- exact SPDX expression for source and packages; +- whether all approved subjects use the same expression; +- whether any artifact is excluded pending review; and +- who owns future license changes. + +## `P7-OD-002`: inbound contribution policy + +### Options + +- **DCO:** lightweight contributor attestation tied to commits. +- **CLA:** explicit contributor agreement that may cover broader copyright, + patent, and relicensing terms. +- **No external contributions yet:** keep contribution intake closed until + counsel and ownership records are ready. + +### Tradeoff + +A DCO usually has less contributor friction. A CLA can provide a more explicit +rights record but adds legal and operational complexity. The correct choice +depends on the intended commercial and governance model, not release tooling. + +### Owner must state + +- DCO, CLA, or temporarily closed intake; +- policy text owner and storage location; +- effective date; and +- handling of contributions already present. + +## `P7-OD-003`: artifact catalogue + +### Current fact + +The workspace contains 95 packages. Current metadata treats 60 Rust packages +as publishable and 35 as private. The release checks also build npm, Python, +WASM, formal, compliance, fixture, benchmark, and documentation artifacts, but +they are not yet one approved subject catalogue. + +### Options + +1. **Complete current publishable set:** treat all 60 Rust crates plus every + maintained binding and evidence bundle as RC subjects. +2. **Maintained consumer surface:** approve only packages intended for external + consumption and explicitly mark other packages `publish = false` before the + candidate. +3. **Evidence-only candidate:** publish source and assurance subjects first, + while preparing but not distributing package subjects. + +### Tradeoff + +Publishing every technically publishable crate creates immediate compatibility +and support expectations across a large surface. Selecting only the maintained +consumer surface requires an explicit dependency-closure and exclusion review. + +### Owner must state + +- every approved subject family; +- every explicit exclusion and reason; +- which subjects are prepared but not published; +- supported platforms for native subjects; and +- which packages carry preview versus release-candidate labeling. + +## `P7-OD-004`: registry publication + +### Candidate locations + +- GitHub prerelease and release attachments; +- crates.io for approved Rust crates; +- npm for `@auths-dev/proof`; +- PyPI for the approved Python package; +- GHCR or another OCI registry for images or assurance bundles; and +- preparation-only content-addressed staging with no public publication. + +### Recommended default + +Prepare every approved subject, but publish only to registries explicitly named +by the owner. Use prerelease semantics everywhere. A registry not named in the +decision receives no publication credential or workflow permission. + +### Owner must state + +- registry-by-subject matrix; +- public, private, staged, or not-published state; +- trusted-publishing identity per registry; +- withdrawal behavior; and +- whether the first RC is an external distribution event. + +## `P7-OD-005`: supply-chain target + +### Options + +- signed hosted-build provenance meeting SLSA Build L2; +- a stronger approved target after assessing runner hardening; or +- preparation-only evidence with an explicit limitation and no public RC. + +### Recommended target + +Target SLSA 1.2 Build Level 3 from the first RC. Level 3 requires a hardened +builder that protects provenance generation and isolates build runs; it is not +achieved merely by adding a signature to an ordinary workflow. Treat failure +to establish the target as an RC blocker rather than silently relabeling Level +2 evidence as sufficient. Provenance identifies how an artifact was built; it +does not claim that the artifact is secure or defect-free. + +### Owner must state + +- target level and specification version; +- approved hosted builder and workflow identity; +- accepted limitations; and +- consumer verification policy. + +## `P7-OD-006`: SBOM baseline + +### Current fact + +The repository emits and validates CycloneDX 1.5 for Cargo metadata. It does +not yet emit the required SPDX release baseline or cover every possible subject +unambiguously. + +### Options + +1. SPDX JSON as the normative release SBOM, retaining CycloneDX as additional + evidence. +2. SPDX JSON only after the owner selects the exact supported SPDX version and + profile. +3. Defer external distribution until tooling can cover all approved subjects. + +### Recommended default + +Use SPDX JSON as the normative baseline and retain CycloneDX where it adds +consumer value. Generate evidence inside the release build and bind it to exact +subject digests. + +### Owner must state + +- exact SPDX version/profile; +- per-subject versus aggregate document model; +- whether CycloneDX is retained; and +- validation and consumer-tool expectations. + +## `P7-OD-007`: tag convention + +### Existing constraint + +The current release check accepts a `v*` tag only when it exactly equals +`v`. It does not accept the target-state example +`auths-proof-v1.0.0-rc.1` without implementation changes. + +### Candidate conventions + +- `auths-proof-v1.0.0-rc.1`, which names the product explicitly; +- `v1.0.0-rc.1`, which is conventional and compatible with many registry + tools; or +- another semver-compatible immutable pattern recorded before tooling changes. + +### Owner must state + +- exact grammar; +- relationship to workspace and package versions; +- ordinal increment and withdrawal policy; and +- whether one tag covers every subject family. + +## `P7-OD-008`: release approvers + +### Requirement + +At least one named human approver must be distinct from the build identity. +The approval protects promotion of already prepared bytes; it must not trigger +a hidden rebuild. + +### Owner must state + +- person or repository role allowed to approve; +- minimum approver count; +- protected GitHub environment or equivalent control; +- approval-record retention; and +- emergency withdrawal authority. + +## `P7-OD-009`: signing identity + +### Options + +- GitHub artifact attestations bound to repository, workflow, commit, and + subject digest; +- an approved Sigstore identity and bundle; +- registry-native trusted-publishing provenance plus an additional release + attestation; or +- no external publication until an identity is approved. + +### Recommended default + +Use GitHub-hosted OIDC as the keyless identity for the first GitHub-built RC +and produce Sigstore attestations for exact release-subject digests, provided +the reusable builder and verification policy satisfy the approved +supply-chain target. Preserve the signed attestation bundle and trust material +inside the evidence bundle so consumers can verify offline. + +This is release-infrastructure identity, not an Auths identity method. The +protocol, verifier, SDK, runtime, and proof exchange MUST NOT require GitHub, +OIDC, Sigstore services, or network access. Independent reproducible +preparation remains a separate evidence path. A hosted release builder is a +declared trusted component, not centralized plumbing imposed on Auths users. + +### Owner must state + +- issuer and identity subject; +- allowed workflow and reusable-workflow chain; +- repository and ref restrictions; +- verification command and trust roots; and +- rotation or compromise response. + +### Auths is a complementary authorization layer + +An Auths proof can authorize the exact promotion action: a named owner permits +one candidate commit and release-manifest digest to be promoted under one tag +to one registry set before an expiry. The resulting receipt can travel with +the release evidence and makes a denial terminal for the same inputs. + +That is different from build provenance. Auths answers whether an actor had +authority for the promotion. SLSA and Sigstore provide evidence about which +builder produced which bytes and under which workload identity. SPDX describes +the subject's software components. Reproducibility compares independent +outputs. None should be relabeled as another. + +Candidate-built code must not be the first RC's sole judge of its own release +authority. The first candidate may emit an Auths receipt as defense-in-depth. +A later candidate can make it a mandatory gate using a previously reviewed, +digest-pinned Auths verifier or another independently qualified bootstrap. + +## `P7-OD-010`: public claim approver + +### Requirement + +Phase 8 needs a named technical owner who approves exact wording and scope. The +approver cannot turn missing evidence into a stronger claim. + +### Owner must state + +- named person or repository role; +- approval-record location; +- whether a second formal/security reviewer is required; +- who may suspend a claim after a finding; and +- reapproval conditions after an RC or claim change. + +## `P7-OD-011`: vulnerability and CRA ownership + +### Required separation + +The owner must distinguish: + +- security contact and coordinated-disclosure operations; +- release withdrawal authority; +- external distribution scope; +- manufacturer or steward questions for each artifact; and +- counsel's legal conclusions. + +### Owner must state + +- security contact or role; +- protected report channel; +- disclosure and embargo owner; +- whether the first RC is externally distributed in the EU or elsewhere; +- counsel-reviewed CRA role when applicable; and +- explicit deferral if external distribution is not yet in scope. + +This guide does not determine legal scope. + +## Fast response template + +The owner may answer in one block: + +```yaml +phase7_release_decisions: + P7-OD-001: {status: approved, decision: "...", owner: "..."} + P7-OD-002: {status: approved, decision: "...", owner: "..."} + P7-OD-003: {status: approved, decision: "...", owner: "..."} + P7-OD-004: {status: approved, decision: "...", owner: "..."} + P7-OD-005: {status: approved, decision: "...", owner: "..."} + P7-OD-006: {status: approved, decision: "...", owner: "..."} + P7-OD-007: {status: approved, decision: "...", owner: "..."} + P7-OD-008: {status: approved, decision: "...", owner: "..."} + P7-OD-009: {status: approved, decision: "...", owner: "..."} + P7-OD-010: {status: approved, decision: "...", owner: "..."} + P7-OD-011: {status: approved, decision: "...", owner: "..."} +``` + +Conditions and evidence references may be added per decision. Missing entries +remain unresolved and continue to block their affected release surfaces. diff --git a/docs/plans/PHASE_7_RELEASE_OWNER_DECISIONS.md b/docs/plans/PHASE_7_RELEASE_OWNER_DECISIONS.md index 6fb0710..5b58565 100644 --- a/docs/plans/PHASE_7_RELEASE_OWNER_DECISIONS.md +++ b/docs/plans/PHASE_7_RELEASE_OWNER_DECISIONS.md @@ -2,9 +2,10 @@ ## 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. +All 11 decisions were approved by the repository owner on 2026-07-31. This +document records policy approval only. It does not authorize an artifact +publication, RC tag, package upload, claim publication, repository-setting +change, secret upload, or external-review engagement. ## Governing specification @@ -15,27 +16,214 @@ 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 +[Phase 7 owner decision guide](PHASE_7_OWNER_DECISION_GUIDE.md) explains the +available choices and their tradeoffs without approving them. + 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. +prepare read-only analysis before the full Phase 7 entry gate passes. 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 | +| `P7-OD-001` | Release license | Keep `MIT OR Apache-2.0` through v1 | Exact license expression approved for RC package and release metadata | approved | +| `P7-OD-002` | Inbound contribution policy | Choose DCO or CLA with counsel | Selected policy, responsible owner, and effective date | approved | +| `P7-OD-003` | Artifact catalogue | Source archive, publishable crates, maintained bindings, WASM/native artifacts, assurance bundle | Exact in-scope and excluded release subjects | approved | +| `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 | approved | +| `P7-OD-005` | Supply-chain target | SLSA Build L3 for the first RC | Approved target and any explicitly accepted limitation | approved | +| `P7-OD-006` | SBOM baseline | SPDX JSON; retain CycloneDX only as additional evidence | Required SPDX version/profile and optional secondary formats | approved | +| `P7-OD-007` | Tag convention | One immutable semver-compatible RC form | Exact tag pattern and initial ordinal policy | approved | +| `P7-OD-008` | Release approvers | At least one named human approver distinct from build identity | Named approver or approver role and protected-environment rule | approved | +| `P7-OD-009` | Signing identity | GitHub artifact attestation backed by public Sigstore | Exact issuer, subject, workflow identity, and verification policy | approved | +| `P7-OD-010` | Public claim approver | Named technical owner | Approver identity or role and approval-record location | approved | +| `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 | approved interim policy | + +## Approved records + +All records in this section were approved by the repository owner on +2026-07-31. `owner: repository-owner` means the human repository owner, not a +workflow, build identity, or autonomous agent. + +### `P7-OD-001` + +```yaml +decision_id: P7-OD-001 +status: approved +decision: "Keep MIT OR Apache-2.0 for the open core through v1." +owner: repository-owner +decided_at: 2026-07-31 +conditions: [] +``` + +### `P7-OD-002` + +```yaml +decision_id: P7-OD-002 +status: approved +decision: "Use a Developer Certificate of Origin (DCO) for external contributions." +owner: repository-owner +decided_at: 2026-07-31 +conditions: + - "The policy and sign-off mechanism must be implemented and tested before public contributor recruitment." +``` + +### `P7-OD-003` + +```yaml +decision_id: P7-OD-003 +status: approved +decision: "Use the lean SDK-first release surface: auths-proof and auths-proof-sdk as the supported Rust roots, @auths-dev/proof on npm, auths-proof on PyPI, plus the source archive and assurance bundle." +owner: repository-owner +decided_at: 2026-07-31 +evidence_or_advice: "https://github.com/auths-dev/auths-proof/issues/51" +conditions: + - "Generate and verify the exact crates.io normal-dependency closure from the candidate revision; it is currently 27 Rust crates." + - "Rename the current workspace package auths-sdk to auths-proof-sdk before freezing package metadata; the existing crates.io name auths-sdk is already occupied by the superseded project line." + - "Registry-visible dependency crates are supporting implementation packages, not separately promised top-level SDKs." + - "The npm subject owns the prepared WASM boundary and the PyPI subject owns prepared native wheels; their Rust build crates are not additional supported crates.io roots." + - "Defer auths-profile-kit, auths-proof-exchange and its adapters, domain integrations, demos, benchmarks, testkits, fuzz crates, internal tools, CLIs, and hosted services." + - "An unexpected dependency-closure expansion blocks the candidate pending review." +``` + +### `P7-OD-004` + +```yaml +decision_id: P7-OD-004 +status: approved +decision: "Prepare and verify first. Plan a later GitHub prerelease and publication of the approved catalogue to crates.io, npm, and PyPI." +owner: repository-owner +decided_at: 2026-07-31 +evidence_or_advice: "https://github.com/auths-dev/auths-proof/issues/50" +conditions: + - "Preparation is not publication authorization." + - "Publication requires a separate owner authorization for the exact release-manifest digest." + - "No registry outside the recorded matrix receives credentials or artifacts." +``` + +### `P7-OD-005` + +```yaml +decision_id: P7-OD-005 +status: approved +decision: "Require SLSA 1.2 Build Level 3 for every first-RC release subject; Level 2 is not an accepted fallback." +owner: repository-owner +decided_at: 2026-07-31 +conditions: + - "A label, environment check, signature, or ordinary GitHub-hosted job does not establish Level 3 by itself." + - "The implemented builder and provenance path must be assessed against every applicable SLSA 1.2 Build Level 3 producer and build-platform requirement." + - "Any subject whose official build cannot establish Level 3 blocks the candidate or is removed through a new owner-approved catalogue decision." + - "SLSA does not establish source correctness, dependency correctness, or artifact security." +``` + +### `P7-OD-006` + +```yaml +decision_id: P7-OD-006 +status: approved +decision: "Use SPDX 2.3 JSON as the normative release SBOM and retain CycloneDX 1.5 as supplementary evidence." +owner: repository-owner +decided_at: 2026-07-31 +conditions: + - "Bind SBOM predicates to exact release-subject digests." + - "A future SPDX migration requires an explicit evidence-schema revision." +``` + +### `P7-OD-007` + +```yaml +decision_id: P7-OD-007 +status: approved +decision: "Use immutable tags matching auths-proof-v-rc., beginning with auths-proof-v1.0.0-rc.1." +owner: repository-owner +decided_at: 2026-07-31 +conditions: + - "A rejected or withdrawn candidate increments the ordinal; its tag never moves." +``` + +### `P7-OD-008` + +```yaml +decision_id: P7-OD-008 +status: approved +decision: "The repository owner is the human release approver, distinct from the hosted build identity." +owner: repository-owner +decided_at: 2026-07-31 +conditions: + - "An executing agent may perform clerical release steps on the owner's behalf only after the owner authorizes the exact manifest digest." + - "This record is not approval of any not-yet-prepared candidate, tag, or publication." +``` + +### `P7-OD-009` + +```yaml +decision_id: P7-OD-009 +status: approved +decision: "Use keyless GitHub Actions OIDC and GitHub artifact attestations backed by the Sigstore Public Good Instance for first-RC build provenance." +owner: repository-owner +decided_at: 2026-07-31 +evidence_or_advice: + - "https://docs.github.com/en/actions/how-tos/secure-your-work/use-artifact-attestations/use-artifact-attestations" + - "https://docs.github.com/en/actions/how-tos/secure-your-work/use-artifact-attestations/verify-attestations-offline" +conditions: + - "Issuer: https://token.actions.githubusercontent.com" + - "Repository owner ID: 260513770; repository ID: 1310728509." + - "Use the protected release-candidate environment and opt into immutable owner/repository subject identity before relying on the subject policy." + - "Expected immutable subject context: repo:auths-dev@260513770/auths-proof@1310728509:environment:release-candidate; implementation must fail if the emitted certificate identity differs." + - "Use a digest-pinned reusable builder workflow whose exact workflow identity is frozen in the release manifest." + - "Preserve each JSON Sigstore bundle and the contemporaneous trusted-root material for offline verification." + - "Auths protocol, verifier, SDK, runtime, and proof exchange must not require GitHub, OIDC, Sigstore services, or network access." + - "Independent reproducible preparation remains a separate evidence path." +``` + +### `P7-OD-010` + +```yaml +decision_id: P7-OD-010 +status: approved +decision: "The repository owner approves exact public assurance wording. Strong claims remain prohibited until applicable independent review is complete." +owner: repository-owner +decided_at: 2026-07-31 +conditions: + - "Pre-review wording must identify the candidate as pre-audit and preserve all evidence limitations." + - "An external reviewer may require narrower wording but cannot supply evidence for a stronger claim." +``` + +### `P7-OD-011` + +```yaml +decision_id: P7-OD-011 +status: approved +decision: "Use the repository owner and GitHub Security Advisories as the interim private security channel and withdrawal authority. Make no CRA compliance claim." +owner: repository-owner +decided_at: 2026-07-31 +evidence_or_advice: "../../SECURITY.md" +conditions: + - "External EU distribution requiring a legal role determination remains blocked pending qualified advice." + - "The first RC is technical prerelease evidence, not a general-availability product." +``` + +## Auths-native release authorization boundary + +Auths MAY produce a separate authorization proof and receipt for the exact +promotion action. That evidence binds the repository owner, candidate commit, +release-manifest digest, tag, destination registry set, expiry, and permitted +operation. It is complementary to, and MUST NOT replace or relabel: + +- SLSA provenance from the hardened build platform; +- Sigstore/GitHub artifact identity and integrity evidence; +- SPDX SBOMs; +- reproducibility evidence; or +- protected human approval. + +For the first RC, candidate-built Auths code MUST NOT be the sole verifier of +its own release authority. It may run as defense-in-depth and produce +explicitly scoped evidence. A later RC MAY make the Auths authorization check +mandatory only when it uses a previously reviewed, digest-pinned verifier or +another independently qualified non-circular verification path. ## Owner response format @@ -63,13 +251,17 @@ advice. ## Current gate result ```text -Phase 7 entry: BLOCKED -Unresolved owner decisions: 11 -Release implementation permitted: no +Owner-decision subgate: PASSED +Approved owner decisions: 11 +Unresolved owner decisions: 0 +Phase 7 entry: BLOCKED pending merge and entry-revision evidence +Release implementation permitted on this unmerged decision branch: 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. +The owner-decision subgate does not establish the remaining Phase 7 entry +conditions. Release implementation begins in a separate bounded PR only after +this decision record is on `main` and the candidate entry revision has real, +terminal evidence for the other AP-SPEC-032 Section 5 conditions. diff --git a/docs/plans/PHASE_7_RELEASE_READINESS_AUDIT.md b/docs/plans/PHASE_7_RELEASE_READINESS_AUDIT.md index 47899a7..dcf4a0a 100644 --- a/docs/plans/PHASE_7_RELEASE_READINESS_AUDIT.md +++ b/docs/plans/PHASE_7_RELEASE_READINESS_AUDIT.md @@ -82,17 +82,22 @@ At the reviewed baseline: 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. +all 60. `P7-OD-003` selects `auths-proof` and the renamed +`auths-proof-sdk` as the supported Rust roots, their generated +normal-dependency closure, the npm and PyPI bindings, the source archive, and +the assurance bundle. The current local `auths-sdk` package name must change +before metadata freeze because crates.io already contains the superseded +project's package under that coordinate. `P7-OD-004` requires preparation and +verification before a separately authorized publication event. ## 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 | +| Owner-approved release boundary | All 11 decisions are approved on the documentation-only specification branch | Decision record is not yet on `main`; approval does not itself establish the remaining Phase 7 entry evidence | | 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 | +| Complete artifact catalogue | Owner approved the lean SDK-first roots, current 27-crate normal-dependency closure, binding subjects, source, assurance bundle, and explicit deferrals | No machine-readable candidate catalogue or CI-enforced closure/exclusion inventory | | 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 | @@ -100,7 +105,7 @@ registry actions. | 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 | +| RC tag contract | Owner approved `auths-proof-v-rc.`, beginning with `auths-proof-v1.0.0-rc.1` | The existing `GITHUB_REF_NAME == v` rule does not implement the approved convention | | 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 | @@ -143,7 +148,7 @@ 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 +## Approved decision-to-implementation constraints | Decision | Implementation it blocks | | --- | --- | @@ -159,7 +164,7 @@ empty output directories and compare results by the declared class. | `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 +## Bounded follow-up PRs after the full entry gate The following are plans, not authorization: @@ -189,5 +194,6 @@ 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. +No implementation PR may begin until the approved decision record is on +`main` and the other AP-SPEC-032 Phase 7 entry conditions have terminal +evidence. The current documentation branch does not establish that gate. diff --git a/docs/specs/0027-product-grade-typescript-sdk.md b/docs/specs/0027-product-grade-typescript-sdk.md index fad6d08..c607d18 100644 --- a/docs/specs/0027-product-grade-typescript-sdk.md +++ b/docs/specs/0027-product-grade-typescript-sdk.md @@ -12,8 +12,8 @@ the AP-SPEC-033 Phase 9 exit gate 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 +assurance claim, the `auths-proof-sdk` Rust package, `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 @@ -76,7 +76,7 @@ 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 +- `auths-proof-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; 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 index da7c628..edd2d37 100644 --- a/docs/specs/0032-reproducible-release-candidate-and-exact-assurance-claim.md +++ b/docs/specs/0032-reproducible-release-candidate-and-exact-assurance-claim.md @@ -1,7 +1,8 @@ # 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 +**Status:** Specified — owner-decision subgate approved; execution still +requires the remaining Phase 7 entry evidence 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) @@ -148,7 +149,7 @@ An unresolved recommendation in that register is not approval. | 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 | +| Supply-chain target | SLSA 1.2 Build Level 3 for every first-RC subject; no Level 2 fallback | 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 | @@ -329,6 +330,34 @@ and Phase 8 claim registry. ## 9. Phase 7: prepare and promote +### 9.0 Separate build integrity from release authority + +The release program has two related but non-interchangeable trust paths: + +```text +hardened hosted builder -- SLSA/Sigstore --> exact artifact digest + +repository owner -- bounded Auths action --> exact promotion authority +``` + +SLSA/Sigstore evidence identifies the builder, workflow, inputs, and exact +artifact subjects. An Auths proof or receipt MAY additionally establish that a +repository owner authorized one exact promotion action over a candidate +commit, release-manifest digest, tag, destination registry set, and expiry. + +An Auths-native release authorization MUST NOT replace, relabel, or weaken the +required SLSA 1.2 Build Level 3 provenance, Sigstore artifact attestation, +SPDX SBOM, reproducibility comparison, or protected human approval. The Auths +protocol and SDK remain independent of GitHub, OIDC, Sigstore, and hosted +verification services. + +For the first RC, an Auths authorization checked by code built from the same +candidate is defense-in-depth only and MUST NOT be its sole authority gate. A +later RC MAY make the check mandatory when verification uses a previously +reviewed, digest-pinned Auths verifier or another independently qualified +non-circular bootstrap. Any Auths denial is terminal for the same inputs; an +operator or agent MUST NOT turn retry into additional authority. + ### 9.1 Preparation One canonical command MUST prepare the complete candidate from a clean