Unified Resource Addressing Spec (URA)

1. Design Intent

URA is a clean-sheet addressing model with four strict separations:

1. Addressing: where/what is addressed (resource_uri).
2. Identity: who is invoking (subject_id).
3. Tenant context: in which trust scope invocation is authorized (tenant_id).
4. Runtime policy: what a verifier/runtime accepts or rejects.

resource_uri is no longer forced to carry all execution semantics.

2. Compatibility Baseline

2.1 Absolute URI Requirement

resource_uri MUST be an absolute URI (RFC 3986).

2.2 Required Scheme Support

Every conforming implementation MUST support:

1. https
2. http
3. wss
4. ws
5. easynet

Implementations MAY support extra schemes by explicit runtime policy.

2.3 Web Compatibility Guarantees

For http/https/ws/wss, parsing and serialization MUST use WHATWG URL algorithm outcomes as the primary source of truth for:

1. Host parsing and normalization.
2. Port handling.
3. Path/query/fragment component split.

For network schemes, implementations MUST NOT substitute an RFC 3986-only parser as canonicalization authority. For each runtime release, canonicalization behavior MUST bind to a fixed reference implementation/version (for example specific Node/Go/Rust/Java runtime versions) to avoid signing-byte drift from upstream parser changes.

3. Security and Signed-Bytes Contract

1. Verifier MUST canonicalize resource_uri before signature verification.
2. Signed bytes MUST use UTF-8 bytes of the canonical URI string.
3. Canonical re-serialization byte mismatch MUST fail closed as INVALID_RESOURCE_URI.
4. URI fragment (#...) MUST be absent in signed invocation addresses.
5. URI userinfo (user:pass@) MUST be rejected for network schemes.
6. Canonical URI string bytes MUST be the only bytes used for routing, authorization, and policy lookup.
7. Runtime components MUST NOT apply additional decode/normalize passes after canonicalization.

3.1 Signed Profile Selection

Invocation envelopes using URA v2 MUST carry an explicit uri_profile field:

1. Allowed values: web-safe-v2, easynet-strict-v2, easynet-v1-compat.
2. uri_profile MUST be included in signature input.
3. Verifier MUST select canonicalization behavior strictly from signed uri_profile.
4. Implicit profile inference is forbidden except explicitly configured migration mode.
5. Runtime MUST enforce a per-endpoint allowed-profile whitelist before canonicalization.
6. Allowed-profile whitelist MUST come from static runtime configuration and MUST NOT be derived from request content.

3.2 Verifier Sequencing (Normative)

Verifier order for URI handling is:

1. Parse envelope structure and read unsigned field shapes, including uri_profile.
2. Validate uri_profile against runtime allowed-profile whitelist; on mismatch, reject immediately before any URI parsing/canonicalization.
3. Canonicalize resource_uri using the extracted uri_profile.
4. Verify signature over signed fields, including uri_profile, and require signed resource_uri bytes to equal canonical URI bytes.
5. Reject request if any canonicalization or byte-equality check fails.

Reading uri_profile before signature verification is an intentional bootstrap dependency. Trust is established only after signature verification succeeds. Before signature verification completes, uri_profile is untrusted selector input and MUST be used only for parser/canonicalization path selection, not for authorization or policy grants. Tenant authorization semantics are outside URI canonicalization and are defined in section 7.

4. Canonicalization Algorithm (Normative)

Given (raw_resource_uri, uri_profile):

1. Precondition: uri_profile whitelist validation from section 3.2 has already succeeded.
2. Parse as absolute URI.
3. Require signed uri_profile (section 3.1).
4. Branch by scheme class and profile:
   • Network schemes (http/https/ws/wss):
     • Canonicalization MUST use WHATWG URL parser + serializer output.
     • Host normalization follows WHATWG + UTS 46 processing.
     • Default ports are removed by canonical serializer behavior.
     • Empty path canonicalizes to /.
     • Fragment presence is a hard reject.
     • Userinfo presence is a hard reject.
     • No extra RFC 3986 post-processing pass is allowed.
   • easynet scheme:
     • Parse and validate using section 6 grammar.
     • easynet-strict-v2 and web-safe-v2 canonical output MUST use empty authority form (easynet:///...).
     • easynet-v1-compat canonical output MUST use legacy authority form from Core v1 (easynet://r/...).
     • Lowercase structural tokens (namespace, scope, subject-type, resource-kind).
     • Normalize Unicode text components required by section 6.8 to NFC.
     • Validate percent triplets; invalid triplets are rejected.
     • Percent triplet hex digits canonicalize to uppercase.
     • Percent triplets for unreserved chars (A-Z a-z 0-9 - . _ ~) decode exactly once.
     • Reserved-character triplets are preserved encoded.
5. Apply query policy from signed uri_profile:
   • web-safe-v2: preserve pair order and duplicates.
   • easynet-strict-v2: tenant_id first when present, then stable-sort remaining pairs by (key_bytes, value_bytes).
   • easynet-v1-compat: apply Core v1 query rules (tenant_id first, ext keys ascending, duplicate keys invalid).
6. Serialize canonical URI string.

Implementations MUST expose canonicalization as a pure function.

5. Addressing Profiles

URA v2 defines three canonical profiles:

5.1 web-safe-v2 (Default)

Purpose: maximum interoperability with internet URL behavior.

1. Query order preserved.
2. Duplicate query keys preserved.
3. Tenant is carried outside URI by default.
4. For easynet scheme, canonical authority/path shape matches easynet-strict-v2 (easynet:///...); difference is query handling policy.
5. Producer is responsible for deterministic query construction when signature stability is required; verifier does not reorder query pairs for this profile.

5.2 easynet-strict-v2

Purpose: deterministic internal protocol addresses with stronger normalization.

1. tenant_id is first when present; remaining pairs are stable-sorted by (key_bytes, value_bytes).
2. Profile-specific URI constraints may require presence/absence of specific query keys.
3. Suitable for protocol-native resource identifiers and conformance suites.

Profile selection is explicit and signed (section 3.1).

5.3 easynet-v1-compat

Purpose: deterministic bridge profile for existing Core v1 signed traffic.

1. Only valid for scheme easynet.
2. Canonicalization behavior follows Core v1 rules, including authority-host form and query constraints.
3. Intended for migration windows, not new protocol-native authoring.
4. Runtime policy SHOULD disable this profile by default and enable it only for explicitly migrated endpoints.

Cross-profile signature rule:

1. Different uri_profile values can produce different canonical URI bytes for the same logical target.
2. Signatures are intentionally non-interoperable across profiles.

6. easynet Scheme v2

easynet scheme canonicalization uses URA grammar and rules in this section, not WHATWG URL network-scheme parsing. Implementations MUST NOT use WHATWG URL parser for easynet URIs at any stage, including pre-validation parsing.

6.1 Shape

easynet:///{namespace}/{scope}/{subject-type}/{subject-value}/{resource-kind}/{resource-path}[@version-ref][?query]

Canonical URA v2 native form uses empty authority (easynet:///), with namespace as path segment 1. Canonical serializer MUST emit exactly easynet:/// prefix for URA v2 native easynet URIs and MUST NOT collapse to easynet:.

6.2 Namespace

namespace defines addressing domain, not actor identity.

Core namespaces:

1. r (resource addressing)
2. resolve (identity/key lookup endpoints)
3. registry (catalog/index resources)
4. invoke (invocation gateway resources)

Extension namespaces:

1. x.<namespace-token> where namespace-token matches [A-Za-z][A-Za-z0-9-]{0,31}.

6.2.1 Core Namespace Semantics

1. r identifies protocol resource addresses (capabilities, invocation resources, manifests).
2. resolve identifies identity/key resolution endpoints and metadata resources.
3. registry identifies indexing/discovery resources.
4. invoke identifies invocation gateway/control-plane endpoints, not capability resource identities.
5. Capability resources that are executed by runtime policy MUST be addressed under r unless an extension profile explicitly states otherwise.
6. In Core invocation envelopes, resource_uri MUST use r namespace; invoke namespace URIs MUST NOT be used as resource_uri values.

6.3 Scope

scope values:

1. pub
2. org
3. prv

6.4 Subject Type

Core subject types:

1. pkh
2. reg
3. node

Extension subject types:

1. x.<namespace>.<token>

Parser MUST accept valid extension forms. Runtime MUST decide allow/deny via policy.

6.5 Resource Kind

Core kinds:

1. abilities
2. invocations
3. manifests
4. policies
5. keys

Extension kinds:

1. x.<namespace>.<token>

Kind semantics are namespace-scoped: the same kind token can carry different domain meaning under different namespaces unless a profile explicitly states shared semantics.

6.6 Segment Character Model

1. subject-value and resource-path segments are Unicode text.
2. Canonical form MUST serialize them using UTF-8 + percent-encoding normalization from section 4.
3. Raw % that is not part of a valid percent triplet is invalid.
4. For URA v2 native easynet profiles (web-safe-v2, easynet-strict-v2), query keys MUST match ^[A-Za-z0-9._-]{1,64}$ and are not Unicode-normalized.

6.7 Version Reference

Accepted forms:

1. <major>.<minor>.<patch>
2. <major>
3. sha256:<64hex>
4. <semver>+sha256:<64hex>
5. <major>+sha256:<64hex>

Validation constraints:

1. <major>.<minor> form is invalid.
2. Numeric identifiers in semver fields MUST match 0|[1-9][0-9]* (no leading zeros except literal 0).
3. Invalid semver text is rejected; there is no pass-through mode for malformed version refs.
4. URA version references are not semver ranges; @1 is a pinned shorthand, not 1.x.x.

Canonicalization:

1. <major> -> <major>.0.0
2. Digest hex -> lowercase
3. <semver>+sha256:<digest> applies semver validation plus digest lowercase normalization.
4. Signature domain uses expanded canonical bytes; @1 and @1.0.0 intentionally collapse to the same canonical URI bytes.

6.8 Unicode Normalization Policy

1. For easynet scheme, canonicalization MUST normalize subject-value, each resource-path segment, and query values to Unicode NFC before percent-encoding normalization.
2. Canonicalization MUST NOT apply NFKC/NFKD compatibility folding.
3. Producers SHOULD still normalize at input boundary to reduce user-visible surprises before signing.

7. Tenant Semantics (Decoupled by Default)

Tenant semantics are policy-layer constraints and MUST NOT be globally hardcoded into URI grammar.

Scope boundary:

1. URA defines URI behavior only; invocation envelope schema is defined in docs/00-foundation/core-spec-v1.md section 8.
2. In Core envelope terms, tenant value is carried in tenant_id; URA does not redefine envelope field naming.
3. Runtime tenant context binding interface is implementation-specific but enforcement outcomes are mandatory.

7.1 Portable Tenant Mode (Default)

1. URI does not need tenant_id.
2. Tenant authorization is enforced via envelope and runtime context.

7.2 Bound Tenant Mode (Optional Profile)

For ecosystems needing URI-level tenant binding:

1. org/prv URIs MUST include tenant_id.
2. pub URIs MUST NOT include tenant_id.
3. URI tenant and envelope tenant MUST match.

Bound mode is a profile choice, not a global protocol axiom. Bound tenant profile identifier is easynet-bound-tenant-v2 (runtime policy profile; not a uri_profile value).

8. Validation Rules

1. Reject non-absolute URI.
2. Reject URI with fragment.
3. Reject URI with userinfo for network schemes.
4. Reject invalid IDNA host normalization results.
5. Reject invalid percent triplets.
6. Reject invalid extension token grammar.
7. Reject missing or unsigned uri_profile.
8. Reject any execution path that performs post-canonicalization decode/normalize.
9. Reject uri_profile = easynet-v1-compat when scheme is not easynet.
10. Reject uri_profile values not allowed by endpoint/runtime policy whitelist.
11. For easynet with web-safe-v2 or easynet-strict-v2, reject any non-empty authority component.
12. For easynet-v1-compat, authority MUST be exactly r.
13. For URA v2 native easynet profiles, reject query keys not matching ^[A-Za-z0-9._-]{1,64}$.

9. Migration from Core v1.0

9.1 Compatibility Contract

Existing v1 URIs like:

easynet://r/org/reg/agent.quote-bot/abilities/order.quote@1.0.0?tenant_id=acme

remain verifiable under easynet-v1-compat.

9.2 Re-Authoring to Strict v2

Strict v2 canonical form for equivalent addressing intent is:

easynet:///r/org/reg/agent.quote-bot/abilities/order.quote@1.0.0?tenant_id=acme

Migration to easynet-strict-v2 requires re-signing because canonical bytes can change.

9.3 Behavioral Shift

1. Canonical easynet URI uses empty authority with namespace in path segment 1.
2. Subject/resource taxonomies are extensible by grammar and constrained by policy.
3. Percent-encoding is normalized, not globally forbidden.
4. Tenant-in-URI is profile-selectable.
5. Query canonical bytes may differ from v1 outside easynet-v1-compat.
6. Version shorthand (@1) collapses into expanded canonical form (@1.0.0) for signatures.
7. For the same logical URI target, different signed uri_profile values are intentionally signature-incompatible.

10. Conformance Requirements

Each implementation MUST provide:

1. At least 300 total canonicalization vectors across http/https/ws/wss/easynet.
2. At least 40 network-scheme baseline vectors (http/https/ws/wss) covering parse/serialize edge cases independent of IDN.
3. At least 60 IDN/host normalization vectors (including invalid IDNA cases).
4. At least 50 percent-encoding and path normalization vectors, including at least 30 negative vectors.
5. At least 50 query/profile vectors covering duplicate keys, ordering, and profile divergence behavior.
6. At least 40 easynet grammar/version/NFC vectors.
7. At least 30 migration vectors covering easynet-v1-compat verification and strict-v2 re-signing.
8. Cross-runtime parity execution on Node/Go/Rust/Java proving identical canonical bytes for the full normative vector corpus.

Draft-phase delivery flexibility:

1. During draft releases, provisional conformance MAY be declared with at least 60% of total vector targets implemented.
2. Provisional conformance still MUST include complete security-critical negatives: fragment rejection, userinfo rejection, invalid percent triplets, profile whitelist rejection, and signature/profile mismatch cases.
3. Final conformance requires 100% of category minimums above.

Normative vector registry location:

1. reports/ura-v2-conformance/

Ownership:

1. Foundation protocol maintainers are responsible for accepting and versioning vector updates.

11. Examples

11.1 Internet-Native

https://api.example.com/v1/tools/list?tag=alpha&tag=beta
https://xn--fsqu00a.xn--0zwm56d/path/%E6%B5%8B%E8%AF%95
wss://stream.example.com/events?cursor=42

11.2 Easynet-Native

easynet:///r/org/reg/agent.quote-bot/abilities/order.quote@1.0.0?tenant_id=acme
easynet:///registry/pub/reg/global.index/invocations/catalog@2
easynet:///x.lineage/prv/x.research.agent/lineage-root/x.lineage.snapshot/main@3+sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa

12. Threat Model

URA v2 security review MUST include at least these attack classes:

1. Signature confusion: attacker attempts to alter canonicalization path/profile without invalidating signature.
2. Parser differential: different runtimes produce different canonical bytes from identical input.
3. IDN spoofing: visually confusable hosts or invalid UTS 46 transitions.
4. Query collision/reorder: duplicate keys or reordered pairs change semantic meaning.
5. Normalization replay: equivalent-looking Unicode/percent forms are replayed to bypass policy.
6. Downgrade to migration profile: endpoint inadvertently accepts easynet-v1-compat outside migration window.

Mitigation baseline:

1. Signed uri_profile.
2. Static profile whitelist.
3. Fail-closed canonical byte equality checks.
4. Cross-runtime vector parity gates.

13. URI Error Code Registry

URA-level failures map to deterministic error codes:

1. INVALID_RESOURCE_URI: parse/canonicalization failure or canonical-byte mismatch.
2. URI_PROFILE_UNSUPPORTED: unknown uri_profile value.
3. URI_PROFILE_NOT_ALLOWED: profile rejected by endpoint whitelist.
4. URI_SCHEME_NOT_ALLOWED: scheme rejected by runtime policy.
5. URI_AUTHORITY_NOT_ALLOWED: non-empty authority where forbidden by profile.
6. URI_IDNA_INVALID: host normalization failure.
7. URI_PERCENT_ENCODING_INVALID: invalid percent triplet or disallowed decode form.

If a runtime uses Core v1 error surfaces, implementations MAY map 2-7 to INVALID_RESOURCE_URI, but internal telemetry SHOULD retain precise sub-code.

14. Extension Namespace Registry Policy

Registry scope:

1. Core namespaces (r, resolve, registry, invoke) are reserved.
2. Extension namespaces use x.<namespace-token>.

Conflict policy:

1. Namespace allocation follows first-registered ownership in Foundation registry records.
2. Ownership updates require signed proof from current owner key binding.
3. Conflicting claims fail closed until governance review resolution.

Registration metadata minimum:

1. Namespace token.
2. Owner subject identifier.
3. Contact/maintainer pointer.
4. Semantics document URL/path.
5. Security considerations section.