Publaryn 1.0 Release Contract

This document defines the intended product contract for Publaryn 1.0.0. It exists to keep the README, concept, ADRs, code, tests, and operator expectations aligned to one shared baseline.

1. Scope of 1.0.0

Publaryn 1.0.0 is the first release that should be treated as a coherent, production-oriented, self-hostable multi-ecosystem package registry baseline.

1.1 In scope

• native protocol adapters for every ecosystem currently mounted in the API
• a unified management API for package, release, repository, organization, team, namespace, token, audit, search, trusted-publisher, and security-finding workflows
• public and authenticated private package discovery
• quarantine-first publication and immutable artifact storage
• hosted repository kinds public, private, staging, and release
• organization-first governance with delegated package, repository, and namespace team access
• a web portal covering package discovery, package details, version details, account settings, token management, MFA, and dedicated organization workspaces
• background-job driven scanning, reindexing, and cleanup infrastructure
• minimal platform-admin queue visibility through GET /v1/admin/jobs plus a documented recovery runbook
• liveness/readiness probes for self-hosted deployments, with readiness requiring PostgreSQL and, when Redis-backed features are configured, Redis connectivity
• CI, validation commands, and container builds that cover the documented stack
• CSV export for organization audit and security views

1.2 Explicitly deferred beyond 1.0

• proxy, mirror, and virtual repositories
• Maven snapshot repositories and generic promotion pipelines
• federated registries, regional replication, and air-gapped synchronization
• billing, commercial tiering, and monetization features
• enterprise SSO, SAML, and SCIM
• full operator consoles for abuse handling and takedowns beyond the current quarantine and audit primitives
• deep attestation policy, signature UX, and broad Sigstore workflows
• trending, popularity, and recommendation discovery surfaces

2. API and adapter matrix

2.1 Control-plane API

The 1.0 management surface is expected to include:

• /v1/auth/*
• /v1/users/*
• /v1/orgs/*
• /v1/org-invitations/*
• /v1/namespaces/*
• /v1/repositories/*
• /v1/packages/*
• GET /v1/search
• nested package security-finding and trusted-publisher routes under /v1/packages/*
• organization security reporting under /v1/orgs/*
• /v1/tokens*
• /v1/audit
• /v1/admin/jobs
• /v1/stats
• /health
• /readiness

2.1.1 Public platform statistics and operator queue visibility

GET /v1/stats is part of the public 1.0 contract. It returns stable top-level aggregate fields for quick instance-level visibility:

• packages
• releases
• organizations
• security_findings_total
• security_findings_unresolved
• artifacts_stored
• job_queue_pending

GET /v1/admin/jobs is the intentionally narrow platform-admin operator surface for queue visibility and recovery triage. It requires a platform-administrator identity with the audit:read scope, supports state, kind, page, and per_page filters, and is operationally documented in docs/operator/job-queue-recovery.md.

2.2 Native adapter matrix

Ecosystem	Mount path	1.0 baseline
npm / Bun	/npm	packument reads, tarball download, search, publish, dist-tags
PyPI / pip	/pypi plus /_/oidc/*	Simple API with resolver metadata projection, file download, legacy upload, trusted-publishing token exchange
Cargo	/cargo/index, /cargo/api/v1	sparse index, publish, download, search, yank, unyank, compatibility owner endpoints
NuGet	/nuget	service index, flat container, registration, search, push, unlist, relist
Maven	/maven	repository reads, metadata generation, checksum reads, deploy-style PUT upload
RubyGems	/rubygems	metadata reads, version listing, gem download, push, yank, API key echo
Composer	/composer	packages index, package metadata, dist download, publish, yank
OCI	/oci	probe, catalog, manifests, blobs, uploads, tags, referrers, delete semantics, orphaned blob cleanup

3. Visibility and search contract

3.1 Visibility model

Publaryn 1.0 distinguishes:

• public
• unlisted
• private
• internal_org
• quarantined

Expected behavior:

• public is readable and searchable by everyone
• unlisted is readable by direct URL but excluded from search and package listing surfaces
• private and internal_org require authenticated visibility through owner, membership, or delegated team access
• quarantined and scanning releases stay hidden from public protocol reads and public artifact downloads

3.2 Search behavior

GET /v1/search is actor-aware in 1.0:

• anonymous callers only see public results
• authenticated callers can also see visible private and organization-internal packages they can access through owner rights, organization membership, or delegated team access
• org and repository filters scope visible results by owner organization slug and repository slug
• search never returns unlisted or quarantined packages

4. Security-flow contract

4.1 Account and token security

1.0 includes:

• password login
• JWT sessions
• scoped API tokens
• TOTP MFA with recovery codes
• per-route scope checks on sensitive write paths
• rate limiting with shared Redis coordination

Deferred beyond 1.0:

• passkeys / WebAuthn
• enterprise IdP federation
• advanced session risk scoring

4.2 Publish and release security

1.0 publish behavior is:

1. create or resolve a release in quarantine
2. store immutable artifacts
3. enqueue scan and indexing work
4. expose the release only after publication rules are satisfied

Security findings are part of the 1.0 baseline, including:

• persisted findings
• package and organization views
• triage through the management API
• audit trails for resolution and reopen actions

Deferred beyond 1.0:

• full malware operations workflow
• formal takedown tooling
• complete SBOM / provenance / attestation productization

5. Supported and unsupported features at 1.0

5.1 Supported

• self-hosted API + frontend deployment
• Postgres, Redis, MinIO/S3-compatible storage, and Meilisearch-backed runtime
• hosted public, private, staging, and release repository kinds
• all mounted adapters listed in this document
• control-plane governance and delegated package, repository, and namespace team access
• actor-aware visibility enforcement for public, unlisted, private, and internal_org resources
• quarantine-first release lifecycle
• background scanning, package reindexing, and OCI blob cleanup
• CSV export for organization audit and security views
• public platform statistics and the minimal /v1/admin/jobs operator queue surface

5.2 Explicitly unsupported or deferred at 1.0

• proxy, mirror, or virtual repository kinds
• Maven snapshot repositories and generic promotion pipelines
• global replication, federation, and air-gapped synchronization workflows
• enterprise SSO, SAML, and SCIM
• billing, quotas as a commercial tiering system, and monetization features
• deep attestation policy, signature UX, and broad Sigstore workflows
• signed client attestations as a complete, polished end-user workflow
• full operator consoles for abuse handling and takedowns beyond the current quarantine and audit primitives
• trending, popularity, and recommendation discovery surfaces

6. Release criteria for 1.0.0

Publaryn 1.0.0 should only ship when all of the following are true:

1. README, concept, this document, and the ADR index agree on the current 1.0 baseline and post-1.0 deferrals.
2. Every mounted adapter has:
   • documented route scope
   • targeted regression coverage for publish/read/auth behavior
   • explicit handling for major edge-case errors
3. The documented CI checks pass:
   • cargo fmt --all -- --check
   • cargo clippy --all-targets --all-features -- -D warnings
   • cargo test -p publaryn-core
   • cargo test -p publaryn-auth --lib
   • cargo test -p publaryn-api --lib
   • cargo test -p publaryn-api --test integration_tests
   • cargo test -p publaryn-auth --test auth_tests
   • bun install --frozen-lockfile
   • bun run typecheck
   • bun test
   • bun run build
4. The Docker smoke build passes.
5. No undocumented adapter or management route is required for the advertised 1.0 user journeys.
6. Release notes clearly separate supported, unsupported, and deferred features.

7. Support and compatibility policy

7.1 Compatibility posture

For 1.0, Publaryn aims for:

• stable documented HTTP paths and wire formats for the management API
• stable documented native adapter behavior for the listed baseline flows
• additive evolution for new optional fields where practical
• ecosystem-correct error responses instead of generic control-plane errors on native routes

7.2 Non-guarantees

Publaryn 1.0 does not guarantee:

• backward compatibility for undocumented internal payload fields
• support for ecosystem features explicitly marked deferred in the ADRs
• parity with every optional feature of upstream public registries

7.3 Operator expectation

1.0 remains a self-hosted open-source release:

• support is best-effort
• upgrades should be accompanied by migration review and validation
• operators are expected to run the documented backing services and CI-grade checks for local changes