EasyNet URL Protocol Standard (Core v1.0)

EasyNet defines a stable URL and verification kernel for agent systems.

Core mental model:

• Agent URL = resource_uri
• Verified Invocation = resource_uri + subject_id + tenant_id + signature

This repository is protocol-first. The priority is a deterministic, cross-language URL and verification standard.

Why This Exists

Modern agent systems typically fail at one or more of these boundaries:

1. Resource addressing is inconsistent across runtimes.
2. Tenant isolation is enforced late (or inconsistently).
3. Invocation authenticity cannot be verified end-to-end.
4. Replay and timestamp controls are not deterministic.

EasyNet Core solves these boundaries with a small normative surface.

Core Scope (Normative)

Core v1.0 includes:

1. Subject identity grammar (subject_id).
2. Canonical easynet:// resource URI grammar.
3. Hard tenant constraints for pub/org/prv.
4. Invocation envelope + JCS canonical signing + Ed25519 verification.
5. Deterministic verifier pipeline and fail-closed behavior.
6. Local Resolve(subject_id, key_id?) for key lookup.

Core v1.0 excludes:

1. Remote/federated resolve service.
2. Full key rotation lifecycle governance.
3. Business orchestration semantics.

URL Structure (At a Glance)

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

Key points:

1. Authority is fixed: r (reserved literal for the EasyNet resource namespace).
2. pub must not include tenant_id in URI query.
3. org/prv must include tenant_id in URI query.
4. @<major> shorthand is allowed as input and canonicalized to @<major>.0.0.
5. Percent-encoding is forbidden.

Normative grammar and canonicalization rules:

• docs/00-foundation/core-spec-v1.md

Deterministic Verification Pipeline (Normative)

The verifier must run checks in this order and stop at first failure:

1. Envelope field validation.
2. URI parse + canonical-form check.
3. Tenant hard-constraint check.
4. Payload hash check.
5. Resolve key + signature verification.
6. Deadline check.
7. Runtime tenant check (org/prv only).
8. Timestamp skew check.
9. Atomic nonce replay guard.
10. Resource-kind policy check.

Normative source of truth for pipeline order: docs/00-foundation/core-spec-v1.md section 10.1.

Core Error Codes

1. TENANT_REQUIRED
2. TENANT_MISMATCH
3. INVALID_RESOURCE_URI
4. PAYLOAD_HASH_MISMATCH
5. INVALID_SIGNATURE
6. NONCE_REPLAY
7. NONCE_STORE_UNAVAILABLE
8. SUBJECT_NOT_FOUND
9. KEY_ID_NOT_FOUND
10. DEADLINE_EXCEEDED
11. TIMESTAMP_SKEW
12. UNSUPPORTED_RESOURCE_KIND

Reference Implementation Mapping

1. URI parser/canonicalizer: src/resource-uri.js
2. Signature canonicalization + crypto: src/signing.js
3. Deterministic verifier: src/verifier.js
4. Error codes: src/errors.js
5. Tests: test/

Quick Validation

npm test

Recommended Reading Order

For a smooth protocol-first flow:

1. docs/00-foundation/core-spec-v1.md
2. docs/00-foundation/core-implementation-checklist.md
3. docs/00-foundation/nucleus-axon-dendrite-responsibility-model-v1.md
4. src/resource-uri.js
5. src/verifier.js
6. test/resource-uri.test.js
7. test/verifier.test.js

Then read extensions only if needed:

1. docs/10-interop/
2. docs/30-governance/
3. docs/20-product/

Documentation Index

1. Documentation architecture: docs/README.md
2. Writing and change conventions: docs/CONVENTIONS.md
3. Core foundation docs: docs/00-foundation/
4. Interop profiles: docs/10-interop/
5. Product/value docs: docs/20-product/
6. Governance profiles: docs/30-governance/
7. Archive (non-baseline): docs/90-archive/