RFC 0007 — Software Registry Conformance, Ingestion & Interoperability

1. Scope & Architectural Boundary

This document defines the normative requirements for software directories, catalog registries, aggregators, and automated crawlers (collectively termed Registries) that consume, index, and present MSR JSON manifests.

The MSR Standard is an open, independent protocol. A registry (such as MySoftRank, a package index, or an AI discovery agent) is an independent consumer implementation. To claim MSR Conformance, a registry MUST satisfy the ingestion, network safety, cache discipline, and schema fidelity rules specified herein.

2. Zero-Account Ingestion & Canonical Discovery

Traditional software directories require manual, multi-page form registration behind vendor accounts, causing stale metadata and high onboarding friction. Conforming registries MUST support automated manifest ingestion:

• Canonical Discovery: Registries MUST support automatic resolution of manifests at the well-known URI specified in RFC 0001: https://<entity.domain>/.well-known/msr.json.
• Zero-Account Ingestion: Registries SHOULD provide an open submission interface allowing any user, developer, or agent to submit a manifest URI without requiring prior user account registration.
• Domain-Bound Authority: Serving a valid manifest over TLS at the product's official root domain (entity.domain) constitutes primary cryptographic and transport authority for technical product metadata. Registries MUST treat this source as authoritative over unverified third-party submissions.

3. Network Safety & SSRF Defense

Allowing arbitrary URL intake introduces Server-Side Request Forgery (SSRF) and resource exhaustion risks. Any crawler or ingestion pipeline in a conforming registry MUST enforce the following safeguards prior to making outbound HTTP requests:

1. Pre-Flight DNS Resolution: The registry crawler MUST resolve target hostnames before issuing requests and strictly reject:
   • Loopback, unspecified and IPv4-mapped IPv6 addresses (127.0.0.0/8, ::1, 0.0.0.0/8, ::/128, ::ffff:0:0/96).
   • RFC 1918 private subnets (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16).
   • Link-local, carrier-grade NAT, unique-local, multicast, reserved and cloud-provider metadata ranges (including 100.64.0.0/10, 169.254.0.0/16, fe80::/10, fc00::/7 and 224.0.0.0/4).
2. Redirect Re-Validation: HTTP redirects (301, 302, 307, 308) MUST be validated against the same IP safety filters at every hop. Registries MUST limit redirect depth to a maximum of 5 hops, reject user-info URL components, and never forward authorization, cookies or publisher-supplied request headers across a hop.
3. DNS Rebinding Resistance: The registry MUST connect only to an address that passed the pre-flight filter, preserve the resolved address for the request, and verify that the connected peer address is still public. A resolver answer MUST NOT be trusted again after a redirect or a new connection without repeating this check.
4. Protocol & Port Enforcement: Only https:// (and optionally http:// for local sandbox testing) on default ports (443 and 80) is permitted. Custom ports are forbidden.
5. Resource Caps: Connection timeouts MUST NOT exceed 8 seconds. Payload downloads MUST be capped at 1 MB after decompression; larger or malformed bodies MUST terminate the connection immediately. Registries MUST parse JSON with duplicate-key detection and MUST NOT fetch URLs, resolve references or execute content contained in a manifest during validation.
6. Response Isolation: A registry MUST send an explicit JSON Accept header, accept only a successful JSON response, disable ambient credentials, and treat the response as untrusted data. It MUST NOT use a manifest URL as a webhook target, proxy target or browser redirect.

4. Semantic Caching & Polling Discipline

Registries MUST be good citizens of the open web and avoid hammering vendor infrastructure:

• Conditional Requests: Registries MUST store the ETag and Last-Modified response headers returned by publishers. Periodic refresh crawlers MUST send If-None-Match and If-Modified-Since headers.
• 304 Handling: On receiving 304 Not Modified, registries MUST NOT re-parse the manifest or alter database records.
• Polling Intervals: Automated crawling intervals MUST NOT exceed once per 6 hours per domain, except when triggered by explicit author webhooks or manual cache purge requests.
• Backoff Etiquette: When a publisher server returns HTTP 429 Too Many Requests or 5xx, the registry MUST respect Retry-After headers and apply exponential backoff.

5. Ingestion Dialects & Canonical Normalization

To facilitate ecosystem migration while preserving the integrity of MSR JSON, registries MAY accept legacy and transitional formats, provided they are normalized to the canonical schema:

Normalization Rules

• Monetary Integrity: Floating-point values (e.g. Program_Cost_Dollars: 29.99) MUST be normalized to exact integer minor units (starting_price_cents: 2999) accompanied by an ISO 4217 currency code ("USD").
• Language Localization: Legacy descriptions (e.g. Char_Desc_250) MUST be assigned to explicit BCP 47 language tags (e.g. entity.descriptions.en.summary).
• Semantic Versioning: Non-conforming version strings MUST be converted or annotated to comply with SemVer 2.0 syntax.
• Artifact Integrity: Legacy download URLs (e.g. Primary_Download_URL) mapped into releases.latest.artifacts[] MUST be omitted until an SHA-256 digest is independently computed or verified. The canonical 2.0 artifact object has no verified member; registries MAY retain that ingestion state internally but MUST NOT add it to a manifest.

6. Domain Authority vs. Vendor Claim Verification

While submission and read-only indexing are zero-account and frictionless, administrative control over a registry listing requires verified domain authority:

• Read & Sync Tier: Open to all. Any agent or user can trigger synchronization of a publicly accessible manifest. The manifest's domain is authoritative for product information.
• Vendor Claim Tier: Actions such as replying to user reviews, configuring paid sponsorship placements, or managing private analytics MUST require domain ownership verification via:
  1. DNS TXT Challenge: A DNS record matching _msr-challenge=<token> on the entity.domain.
  2. Domain Email Confirmation: Verification email dispatched to an address under the same domain (e.g. security@<entity.domain>).
  3. Cryptographic Signature: Manifest signed with an Ed25519 key registered in DNS per RFC 0003.

7. Zero-Drift Rule: Non-Corruption of the Canonical Schema

A registry MUST NOT fork, mutate, or introduce proprietary enum values into the canonical schema while referencing the canonical schema identifier https://msrjson.org/schemas/msr-2.0.json.

Registry-specific operational attributes (e.g. internal review aggregations, editorial rankings, click counters, sponsorship flags) MUST be stored in the registry's own private database. They MUST NOT be injected into published MSR JSON manifests.

8. Claim, Signature and Verification Boundaries

A syntactically valid manifest is a publisher claim, not proof that every statement in it is true. Registries MUST label domain verification, signatures, availability, data residency and audit receipts according to the evidence they independently observed. A registry MUST NOT upgrade a publisher-declared trust.domain_verification.status to verified merely because the field is present.

When validating an RFC 0003 signature, a registry MUST canonicalize the manifest with JCS after removing trust.signatures, identify the advertised algorithm, and reject malformed encodings, unsupported algorithms and failed verification. A signature proves control of a private key at signing time; it does not by itself prove vendor identity, legal compliance, product availability or security quality.

Registries MUST retain the retrieval time, effective URL, response validators and verification outcome needed to explain a displayed trust state. They SHOULD expose a re-check action and MUST downgrade a previously verified state when the proof is revoked, absent or fails on refresh.