diff --git a/astro.config.mjs b/astro.config.mjs index a8247f0..a047bbf 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -59,7 +59,8 @@ export default defineConfig({ { label: 'Invite Keys', link: '/en/invite-keys' }, { label: 'Contract Manifests', link: '/en/contract-manifests' }, { label: 'State Snapshots', link: '/en/state-snapshots' }, - { label: 'ZKPP', link: '/en/zkpp' } + { label: 'ZKPP', link: '/en/zkpp' }, + { label: 'URI Scheme', link: '/en/scheme' } ] }, { diff --git a/src/content/docs/en/scheme.md b/src/content/docs/en/scheme.md new file mode 100644 index 0000000..4f7421e --- /dev/null +++ b/src/content/docs/en/scheme.md @@ -0,0 +1,132 @@ +--- +title: "The `shelter` URI Scheme" +--- + +## Introduction + +The `shelter` URI scheme identifies resources that can be reached through the +Shelter Protocol. These resources are generic and could take various forms. +For example, a resource could refer to a contract, a manifest or a file part, +among other options. Each resource is identified by a self-referencing hash, +which is in the CID format [[CID]](#ref-CID), using the BLAKE2b-256 digest +[[RFC7693]](#ref-RFC7693) and the Base58 [[BASE58]](#ref-BASE58) encoding. + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", +"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be +interpreted as described in [[RFC2119]](#ref-RFC2119). + +In this document, URIs are enclosed in `<` and `>` as described in Appendix C of +[[STD66]](#ref-STD66). Extra whitespace and line breaks are added to present +long URIs -- they are not part of the actual URI. + +## Syntax of a `shelter` URI + +In its simplest form, a `shelter` URI is the `shelter:` string immediately +followed by a CID and nothing else. + +The format syntax of a `shelter` URI is described using the ABNF of +[[STD68]](#ref-STD68): + + shelterURI = "shelter:" [ "//" authority "/" ] cid [ "?" query ] + authority = + query = + cid = + +## Semantics and Operations + +The `shelter` URI scheme is used to identify resources that can be accessed +through the Shelter Protocol. The CID (Content Identifier) portion of the URI +uniquely identifies the resource, and the optional authority and query +components can be used to provide additional context or parameters for +accessing the resource. + +When a `shelter` URI is dereferenced, the client should use the Shelter Protocol +to retrieve the identified resource. The specific operations and behaviors +involved in this process are defined by the Shelter Protocol specification. + +## Encoding + +Any reserved characters, as defined in [[STD66]](#ref-STD66), MUST be encoded +when used in a `shelter` URI. + +## Examples + +This section is non-normative. + +A URI for a resource identified by the CID +`z9brRu3VMfgn81z36GzeKDsZBoUEjsNKccJA5BpZVsorhcefFnZT`: + + + +A URI for the current key named `csk` for a resource (a smart contract, in +this case) identified by the CID +`z9brRu3VMfgn81z36GzeKDsZBoUEjsNKccJA5BpZVsorhcefFnZT`: + + + +A URI for the current key named `csk` for a resource (a smart contract, in +this case) identified by the CID +`z9brRu3VMfgn81z36GzeKDsZBoUEjsNKccJA5BpZVsorhcefFnZT`, to be loaded from a +server located at the address `example.com`: + + + +## Security Considerations + +The security considerations for the `shelter` URI scheme are primarily related +to the security of the Shelter Protocol itself. Implementers SHOULD ensure that +they follow best practices for secure protocol design and implementation, and +they MUST properly validate and sanitize any input or output related to +`shelter` URIs. + +In particular, a Shelter resource can refer to computer code that could result +in dynamic code execution, such as smart contracts, or additional network +requests, such as interacting with a smart contract. In these cases, +implementers SHOULD take care to ensure that dynamically executed code has a +trusted provenance and is properly sandboxed, and that any interactions with +resources follow clear rules understood by users. + +A current limitation of the Shelter URI scheme is that the specific semantics +and content type of a resource is context-dependent, which is something that +could be addressed by embedding content type information within a CID. +Implementers MAY enforce semantics and content type information though this +mechanism. + +## References + + +

+[BASE58] Nakamoto, S. and M. Sporny, "The Base58 Encoding Scheme", +draft-msporny-base58-03, +March 2021. +

+ +

+[CID] Benet, Juan, Ed., "CID (Content IDentifier) Specification", +CID, December 2023. +

+ +

+[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement +Levels", BCP 14, +RFC 2119, March 1997. +

+ +

+[RFC7693] Saarinen, M., Ed. and J. Aumasson, "The BLAKE2 Cryptographic Hash and +Message Authentication Code (MAC)", +RFC 7693, +DOI 10.17487/RFC7693, November 2015. +

+ +

+[STD66] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, +RFC 3986, January 2005. +

+ +

+[STD68] Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: +ABNF", STD 68, RFC 5234, +January 2008. +