Variable zcapSpecHtmlConst
zcapSpecHtml: string = "<!DOCTYPE html>\n<html>\n <head>\n <meta charset='utf-8'>\n <title>Authorization Capabilities v0.4.0-rc.3</title>\n <script src='//www.w3.org/Tools/respec/respec-w3c' class='remove'></script> <script class='remove'>\n var respecConfig = {\n specStatus: \"CG-DRAFT\",\n subtitle: \"An object capability framework for linked data systems\",\n editors: [\n {name: \"Christine Lemmer-Webber\",\n url: \"https://dustycloud.org/\",\n company: \"Spec-Ops\",\n companyURL: \"https://www.spec-ops.io/\"},\n {name: \"Dmitri Zagidulin\",\n company: \"Interop Alliance\",\n companyURL: \"https://interopalliance.org\"},\n {name: \"Manu Sporny\",\n url: \"http://manu.sporny.org/\",\n company: \"Digital Bazaar\",\n companyURL: \"http://digitalbazaar.com/\"},\n {name: \"Benjamin Goering\",\n url: \"https://bengo.is/\"},\n ],\n authors: [\n {name: \"Christine Lemmer-Webber\",\n url: \"https://dustycloud.org/\",\n company: \"Spec-Ops\",\n companyURL: \"https://www.spec-ops.io/\"},\n {name: \"Manu Sporny\",\n url: \"http://manu.sporny.org/\",\n company: \"Digital Bazaar\",\n companyURL: \"http://digitalbazaar.com/\"},\n {name: \"Mark S. Miller\",\n url: \"http://www.erights.org/talks/thesis/\",\n company: \"Agoric\",\n companyURL: \"https://agoric.com\"}],\n license: \"w3c-software-doc\",\n processVersion: 2017,\n edDraftURI: \"https://w3c-ccg.github.io/zcap-spec/\",\n shortName: \"zcap-spec\",\n group: \"credentials\",\n issueBase: \"https://github.com/w3c-ccg/zcap-spec/issues/\",\n otherLinks: [\n {\n \"key\": \"Repository\",\n \"data\": [\n {\n \"value\": \"Git repository\",\n \"href\": \"https://github.com/w3c-ccg/zcap-spec\",\n },\n {\n \"value\": \"Issues\",\n \"href\": \"https://github.com/w3c-ccg/zcap-spec/issues\",\n },\n {\n \"value\": \"Commits\",\n \"href\": \"https://github.com/w3c-ccg/zcap-spec/commits/gh-pages\",\n }\n ]\n }\n ],\n\n // name of the WG\n wg: \"Credentials Community Group\",\n\n // URI of the public WG page\n wgURI: \"https://www.w3.org/community/credentials/\",\n\n // name (with the @w3c.org) of the public mailing to which comments are due\n wgPublicList: \"public-credentials\",\n\n // URI of the patent status for this WG, for Rec-track documents\n // !!!! IMPORTANT !!!!\n // This is important for Rec-track documents, do not copy a patent URI from a random\n // document unless you know what you're doing. If in doubt ask your friendly neighbourhood\n // Team Contact.\n // NOTE: Though not a Working Group, and this spec is not yet rec-track,\n // the CCG follows the W3C Community Contributor License Agreement.\n wgPatentURI: \"https://www.w3.org/community/about/agreements/cla/\",\n };\n </script>\n </head>\n <!-- Style guide for this document:\n - Indent tags appropriately according to nesting depth\n - Newline after every sentence (this helps making reading git diffs\n easier, as well as merging in complicated changes, because a change\n will only affect a sentence at a time rather than a complete\n paragraph)\n - Wrap text at column 79 (the least critical of the three conventions\n since this merely helps the text look nicer in many text editors)\n -->\n <body>\n <section id='abstract'>\n <p>\n Authorization Capabilities (<code>zcap</code> for\n short) provides a\n secure way for linked data systems to grant and express authority\n utilizing the\n <a href=\"https://en.wikipedia.org/wiki/Object-capability_model\">\n object capability model</a>.\n Capabilities are represented as linked data objects which are signed\n with <a href=\"https://w3c-ccg.github.io/ld-proofs/\">\n Linked Data Proofs</a>.\n Zcaps support delegating authority to other entities\n on the network by chaining together capability documents.\n \"Caveats\" may be attached to capability documents which may be used to\n restrict the scope of their use, for example to restrict the actions\n which may be used or providing a mechanism by which the capability may\n be later revoked.\n </p>\n </section>\n <section id='sotd'>\n <p>\n This specification is currently being drafted to be considered as a\n work item for the\n <a href=\"https://w3c-ccg.github.io/\">Community Credentials Group</a>.\n </p>\n </section>\n <section id=\"introduction\">\n <h2>Introduction</h2>\n <p><i>\n This document is being based off of a\n <a href=\"https://github.com/WebOfTrustInfo/rebooting-the-web-of-trust-fall2017/blob/master/draft-documents/lds-ocap/lds-ocap.md\">paper from Rebooting Web of Trust</a>.\n In the early stages of this document some ideas may be better\n described in that paper than yet in this specification.\n </i></p>\n\n <p>\n This document does not cover a specific method for delivering zcap\n invocations to an object, though something like the inbox property and\n associated delivery mechanisms from Linked Data Notifications and\n ActivityPub is one possible system.\n However there is nothing about zcaps that are specific to HTTP; for\n example, both capabilities and invocations could be stored on a\n blockchain or a distributed hash table.\n </p>\n\n <section id=\"zcap-by-example\">\n <h2>Zcap by Example</h2>\n <p>\n Much of modern computing security infrastructure relies on \"who is\n doing something\" using access control lists.\n For example, our friend Alyssa P. Hacker has a car, and she would\n like to drive it.\n In the access control list world, the car itself may scan Alyssa's\n face, determine that Alyssa is the driver, and say \"Welcome Alyssa,\n you are now free to drive.\"\n Talking cars are appealing and fun, but Alyssa may run into\n challenges when she would like to allow others to drive her car.\n </p>\n\n <p>\n Fortunately, there is another paradigm that is even more familiar to\n the car scenario, but less familiar in the context of computing,\n despite providing some superior properties and a greater degree\n of safety: object capabilities.\n Object capabilities focus not on \"who\" is performing an action, but\n upon \"what\" source of authority permits an action to occur.\n As it turns out, Alyssa does not have a talking and face-scanning\n car, she has a car that accepts a car key.\n The car may have no memory of Alyssa whatsoever, but as long as\n Alyssa holds the kind of key that enables her to drive the car, she\n can drive the car.\n Capabilities are very similar to this car metaphor, and we can encode\n this same idea in zcaps.\n </p>\n\n <p>\n The car is the target of this capability chain, and it is the initial\n source of authority on that chain.\n Dereferencing the car's identifier,\n <code>https://whatacar.example/a-fancy-car</code>,\n yields a document whose <code>capabilityDelegation</code> property\n holds the cryptographic material the car uses to make that first\n delegation:\n </p>\n\n <pre class=\"example highlight javascript\">\n{\n \"@context\": [\n \"https://w3id.org/zcap/v1\",\n \"https://w3id.org/security/data-integrity/v2\"\n ],\n\n \"id\": \"https://whatacar.example/a-fancy-car\",\n\n // The initial source of authority on any chain rooted at this car.\n // Alyssa bought the car, so the car's manufacturer provisioned it to\n // recognize one of Alyssa's keys as its delegating key.\n \"capabilityDelegation\": [\n \"https://example.com/i/alyssa/keys/1\"\n ]\n}\n </pre>\n\n <p>\n The following document delegates authority from the car (who always\n has authority over itself) to Alyssa so that she may drive.\n Note that its proof is created with\n <code>https://example.com/i/alyssa/keys/1</code>, the key named\n above in the car's <code>capabilityDelegation</code> property, which\n is what makes the delegation authoritative:\n </p>\n\n <!-- TODO: Should we include the full embedded key? That's better\n practice in general (outside of DIDs) but will make the example\n noisier -->\n <pre class=\"example highlight javascript\">\n{\n \"@context\": [\n \"https://w3id.org/zcap/v1\",\n \"https://w3id.org/security/data-integrity/v2\",\n \"https://autopower.example/\"\n ],\n\n \"id\": \"https://whatacar.example/a-fancy-car/proc/7a397d7b\",\n\n // Since this is the first delegated capability, the parentCapability\n // is the root zcap of the target this capability will operate against\n // (in this case, Alyssa's Car)\n \"parentCapability\": \"urn:zcap:root:https%3A%2F%2Fwhatacar.example%2Fa-fancy-car\",\n\n // We are granting authority specifically to one of Alyssa's\n // cryptographic keys (not to be confused with the car\n // key metaphor!)\n \"controller\": \"https://social.example/alyssa#key-for-car\",\n\n // Finally we sign this object with cryptographic material from\n // Alyssa's Car's capabilityDelegation field, and using the\n // capabilityDelegation proofPurpose.\n \"proof\": {\n \"type\": \"DataIntegrityProof\",\n \"created\": \"2018-02-13T21:26:08Z\",\n \"cryptosuite\": \"eddsa-jcs-2022\",\n \"capabilityChain\": [\n \"urn:zcap:root:https%3A%2F%2Fwhatacar.example%2Fa-fancy-car\"\n ],\n \"proofPurpose\": \"capabilityDelegation\",\n \"proofValue\": \"z2YwC8z3ap7yx1nZYCg4L3j3ApHsF8kgPdSb5xoS1VR7vPG3F561B52hYnQF9iseabecm3ijx4K1FBTQsCZahKZme\",\n \"verificationMethod\": \"https://example.com/i/alyssa/keys/1\"\n }\n}\n </pre>\n\n <p>\n Turning on this car and driving into the sunset is as easy as\n invoking the capability to do so:\n </p>\n\n <pre class=\"example highlight javascript\">\n{\n \"@context\": [\n \"https://w3id.org/zcap/v1\",\n \"https://w3id.org/security/data-integrity/v2\",\n \"https://autopower.example/\"\n ],\n \"id\": \"urn:uuid:ad86cb2c-e9db-434a-beae-71b82120a8a4\",\n \"action\": \"Drive\",\n \"proof\": {\n \"type\": \"DataIntegrityProof\",\n \"cryptosuite\": \"eddsa-jcs-2022\",\n // A linked data document can be an invocation if it has a\n // proofPurpose of capabilityInvocation and links to the capability\n // chain it is invoking\n \"proofPurpose\": \"capabilityInvocation\",\n \"capability\": {\n \"@context\": \"https://w3id.org/zcap/v1\",\n \"id\": \"urn:uuid:d2c83c43-878a-4c01-984f-b2f57932ce5f\",\n \"parentCapability\": \"urn:uuid:f7412b9a-854b-47ab-806b-3ac736cc7cda\",\n \"controller\": \"did:key:dummy\",\n \"expires\": \"2026-01-31T00:00:00Z\",\n \"allowedAction\": [\n \"https://example.com/storage/method/UploadFile\"\n ],\n \"proof\": [\n {\n \"type\": \"DataIntegrityProof\",\n \"cryptosuite\": \"eddsa-jcs-2022\",\n \"created\": \"2026-01-01T00:00:00Z\",\n \"verificationMethod\": \"did:key:bob#bob\",\n \"proofPurpose\": \"capabilityDelegation\",\n \"proofValue\": \"zQeVbY4oey5q2M3XKaxup3tmzN4DRFTLVqpLMweBrSxMY2xHX5XTYV8nQApmEcqaqA3Q1gVHMrXFkXJeV6doDwLWx\"\n }\n ]\n },\n \"created\": \"2016-02-08T17:13:48Z\",\n \"verificationMethod\": \"https://social.example/alyssa/#key-for-car\",\n \"proofValue\": \"...\"\n }\n}\n </pre>\n\n <p>\n Alyssa lives with her roommate and long-time friend Ben Bitdiddle.\n While they're living together, she'd like that he be able to drive\n her car too.\n Capabilities support delegation, so she could delegate a new\n capability to Ben giving him full authority, not unlike going to the\n hardware store and having them copy the car key.\n But Alyssa knows that she and Ben will probably not be roommates\n forever, and she feels no need for him to be able to drive her car\n once they are not, so she would like to have the option to revoke\n his authority.\n In the world of object capabilities, this is entirely possible by\n adding a \"caveat\" that permits future revocation.\n We can imagine this to be like a new car key that has a remote\n destruction mechanism: Alyssa can press a button that she has,\n a wire burns out inside the car key, and the car key will not be usable\n anymore.\n Alyssa generates a new capability document that points at the\n capability she has, adding the caveat:\n </p>\n\n <pre class=\"example highlight javascript\">\n{\n \"@context\": [\n \"https://w3id.org/zcap/v1\",\n \"https://w3id.org/security/data-integrity/v2\",\n \"https://autopower.example/\"\n ],\n \"id\": \"https://social.example/alyssa/caps#79795d78\",\n\n // Pointing up the chain at the capability from which Alyssa was\n // initially gained authority\n \"parentCapability\": \"https://whatacar.example/a-fancy-car/proc/7a397d7b\",\n\n // Alyssa grants authority specifically to one of Ben's\n // cryptographic keys\n \"controller\": \"https://chatty.example/ben/#key-33\",\n\n // Alyssa adds a caveat: Ben can drive her car, unless she flips\n // the bit at this url\n \"caveat\": [\n {\n \"type\": \"ValidWhileTrue\",\n \"uri\": \"https://social.example/alyssa/ben-can-still-drive\"\n }\n ],\n\n // Finally Alyssa signs this object with the key she was granted\n // authority with\n \"proof\": {\n \"type\": \"DataIntegrityProof\",\n \"cryptosuite\": \"eddsa-jcs-2022\",\n \"proofPurpose\": \"capabilityDelegation\",\n \"created\": \"2017-03-28T06:01:25Z\",\n \"verificationMethod\": \"https://social.example/alyssa/#key-for-car\",\n \"proofValue\": \"...\",\n \"capabilityChain\": [\n \"urn:zcap:root:https%3A%2F%2Fwhatacar.example%2Fa-fancy-car\",\n // This should be the full expression of the parentCapability (i.e. Example 1)\n {\n \"@context\": [\n \"https://w3id.org/zcap/v1\",\n \"https://w3id.org/security/data-integrity/v2\",\n \"https://autopower.example/\"\n ],\n \"id\": \"https://whatacar.example/a-fancy-car/proc/7a397d7b\",\n \"parentCapability\": \"urn:zcap:root:https%3A%2F%2Fwhatacar.example%2Fa-fancy-car\",\n \"controller\": \"https://social.example/alyssa#key-for-car\",\n \"proof\": {\n \"type\": \"DataIntegrityProof\",\n \"cryptosuite\": \"eddsa-jcs-2022\",\n \"created\": \"2018-02-13T21:26:08Z\",\n \"capabilityChain\": [\n \"urn:zcap:root:https%3A%2F%2Fwhatacar.example%2Fa-fancy-car\"\n ],\n \"proofValue\": \"eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19lfAFjrWE-4RxhL0gtzSMRX72NR9SRDgaMmkjPA4if0ERbw4R2bnts5sAs8OyhAlbFzBAKOqrFk57AYqwSR2vCw\",\n \"proofPurpose\": \"capabilityDelegation\",\n \"verificationMethod\": \"https://example.com/i/alyssa/keys/1\"\n }\n }\n ]\n }\n}\n </pre>\n\n <p>\n Alyssa hands the car key to Ben, and Ben marks the car key in such\n a way that reminds him that it's specifically to drive Alyssa's car.\n Several months pass and Ben receives a message from Alyssa asking if\n he might enjoy joining her at an award ceremony her university is\n holding.\n Alyssa is already at the university and is getting a ride to the\n venue, so she suggests Ben drive her car and meet her there.\n Ben invokes his capability, the car performs all relevant checks on\n the capability (including that the proof/signature is valid and applicable,\n and that the caveat is still valid), and off Ben drives.\n </p>\n\n <p>\n Ben arrives at the fancy award venue, where there is valet parking.\n The Valet approaches wearing the nametag \"Lem E. Driveit\" and asks\n for a key to park the car.\n Ben remembers he has heard some stories about valets going on\n joyrides and isn't sure if they're true, but decides there's no need\n to take the risk: he can use his capability to create a new, further\n restricted capability which he can delegate to Lem.\n This new car key has the caveat that it can be used to drive up\n to 5 kilometers, but no more:\n </p>\n\n <pre class=\"example highlight javascript\">\n{\n \"@context\": [\n \"https://w3id.org/zcap/v1\",\n \"https://w3id.org/security/data-integrity/v2\",\n \"https://autopower.example/\"\n ],\n \"id\": \"https://chatty.example/ben/caps#2cdea8c1\",\n \"parentCapability\": \"https://social.example/alyssa/caps#79795d78\",\n \"controller\": \"https://lem.example/#key-bf36\",\n\n // Ben adds this caveat: this capability can be used to drive the\n // car, but not for more than 5 kilometers\n \"caveat\": [\n {\n \"type\": \"DriveNoMoreThan\",\n // Alyssa's gauge currently says 123854 kilometers driven,\n // so this is only 5 km more than the current value\n \"kilometers\": 123859\n }\n ],\n\n // Finally Ben signs this object with the key he was granted\n // authority with\n \"proof\": {\n \"type\": \"DataIntegrityProof\",\n \"cryptosuite\": \"eddsa-jcs-2022\",\n \"proofPurpose\": \"capabilityDelegation\",\n \"created\": \"2017-06-13T19:15:03Z\",\n \"verificationMethod\": \"https://chatty.example/ben/#key-33\",\n \"proofValue\": \"...\",\n \"capabilityChain\": [\n \"urn:zcap:root:https%3A%2F%2Fwhatacar.example%2Fa-fancy-car\",\n \"https://whatacar.example/a-fancy-car/proc/7a397d7b\",\n // This is the full expression of the parentCapability (i.e. Example 3)\n {\n \"@context\": [\n \"https://w3id.org/zcap/v1\",\n \"https://autopower.example/\"\n ],\n \"id\": \"https://social.example/alyssa/caps#79795d78\",\n \"parentCapability\": \"https://whatacar.example/a-fancy-car/proc/7a397d7b\",\n \"controller\": \"https://chatty.example/ben/#key-33\",\n \"caveat\": [\n {\n \"type\": \"ValidWhileTrue\",\n \"uri\": \"https://social.example/alyssa/ben-can-still-drive\"\n }\n ],\n \"proof\": {\n \"type\": \"DataIntegrityProof\",\n \"cryptosuite\": \"eddsa-jcs-2022\",\n \"proofPurpose\": \"capabilityDelegation\",\n \"created\": \"2017-03-28T06:01:25Z\",\n \"verificationMethod\": \"https://social.example/alyssa/#key-for-car\",\n \"proofValue\": \"...\",\n \"capabilityChain\": [\n \"urn:zcap:root:https%3A%2F%2Fwhatacar.example%2Fa-fancy-car\",\n // This is the full expression of the parentCapability (i.e. Example 1)\n {\n \"@context\": [\n \"https://w3id.org/zcap/v1\",\n \"https://w3id.org/security/suites/ed25519-2020/v1\",\n \"https://autopower.example/\"\n ],\n \"id\": \"https://whatacar.example/a-fancy-car/proc/7a397d7b\",\n \"parentCapability\": \"urn:zcap:root:https%3A%2F%2Fwhatacar.example%2Fa-fancy-car\",\n \"controller\": \"https://social.example/alyssa#key-for-car\",\n \"proof\": {\n \"type\": \"DataIntegrityProof\",\n \"cryptosuite\": \"eddsa-jcs-2022\",\n \"created\": \"2018-02-13T21:26:08Z\",\n \"capabilityChain\": [\n \"urn:zcap:root:https%3A%2F%2Fwhatacar.example%2Fa-fancy-car\"\n ],\n \"proofPurpose\": \"capabilityDelegation\",\n \"proofValue\": \"z4oey5q2M3XKaxup3tmzN4DRFTLVqpLMweBrSxMY2xHX5XTYVQeVbY8nQAVHMrXFkXJpmEcqdoDwLWxaqA3Q1geV6\",\n \"verificationMethod\": \"https://example.com/i/alyssa/keys/1\"\n }\n }\n ]\n }\n }\n ]\n }\n}\n </pre>\n\n <p>\n (It probably doesn't matter to this scenario, but since it is derived\n from the car key that Ben holds, it also has the same caveat that it\n will also be remote destructed by Alyssa along with Ben's car key\n should she press the relevant button.)\n </p>\n </section>\n\n <section id=\"capabilities-are-safer\">\n <h2>Capabilities Are Safer</h2>\n <p>\n We can see from the above example that using an object capability\n system such as zcap can give us some additional\n power around delegating and restricting the scope of capabilities.\n But object capabilities provide improved safety characteristics\n over Access Control Lists which may make them frequently better\n choices (for more details, see the paper\n <a href=\"http://waterken.sourceforge.net/aclsdont/current.pdf\">\n ACLs Don't</a>).\n Object capability systems are in general more robust against:\n </p>\n\n <ul>\n <li>\n <b>Ambient authority problems:</b>\n For example, in an access control list environment,\n if an attacker gets you to open a message in your email client\n which contains an image which triggers an arbitrary code execution\n vulnerability in the image library it is using, an attacker can\n use this to do everything that you can: they can read or destroy your\n documents, they can run programs as you, and they can in general\n do anything that you can... all from a pin-prick sized vulnerability.\n Properly using an object capability environment, the worst an\n attacker could do is mess with your email (or if the program is\n itself capability aware, they may not be able to do even\n that... they could just display some nasty imagery on your screen,\n which they could do already anyway).\n </li>\n <li>\n <b>Confused deputy attacks:</b>\n For example, browsers and both backend and frontend software for\n the web have frequently struggled with Cross-Site Request Forgery\n attack issues.\n Your browser may both allow websites to access resources on\n other websites and also allow you to log into various websites,\n say a social networking site or a bank.\n A malicious website could use this to its advantage to trick\n your browser into performing actions as you on those other sites...\n say to read from or spam to your social timeline, or to withdraw\n money from your bank account.\n While various techniques to can be used to restrict the scope\n of these attacks, they are notoriously hard to prevent.\n </li>\n </ul>\n\n <p>\n Object capabilities are less vulnerable to these kinds of attacks\n because capabilities are an encoding of \"the principle of least\n authority\" in software development practice.\n Zcaps help bring the power of capabilities to the web, providing\n specific and directed grants of authority.\n </p>\n </section>\n </section>\n <section id=\"terminology\">\n <h2>Terminology</h2>\n <!-- TODO: Add introductory paragraph to this section -->\n <dl>\n <dt>capability</dt>\n <dd>\n Authority which may be invoked to perform some operation upon a\n (linked data) object.\n </dd>\n\n <dt>target</dt>\n <dd>\n The entity that will be acted upon when the capability is invoked.\n </dd>\n\n <dt>capability chain</dt>\n <dd>\n A chain of capability documents which may be used to delegate\n authority to other entities in the system.\n Each capability document in the chain inherits the caveats of\n previous capabilities in the chain and may only be granted by\n entities which have existing authority within the chain.\n </dd>\n\n <dt>caveat</dt>\n <dd>\n Also known as \"attenuation\" within object capability literature,\n a \"caveat\" may be attached to a capability as a restriction on\n how that capability may be used.\n Delegated capabilities will preserve caveats and themselves\n may be further restricted by adding more caveats.\n </dd>\n\n <dt>invocation</dt>\n <dd>\n The \"activation\" of a capability, represented as a linked data\n document which is signed in such a way that matches authority\n granted through a prior capability.\n <!-- TODO: fix up awkward wording here -->\n An invocation may have arguments, similar to how a procedure call\n may have arguments.\n </dd>\n\n <dt>action</dt>\n <dd>\n An argument of an invocation which directs what particular\n functionality of the object is being used.\n For example, an invocation against a file storage service\n may specify either a write action or a read action.\n (Actions are the same as what are frequently called \"methods\" in\n computer programming.)\n </dd>\n\n <dt>parentCapability</dt>\n <dd>\n The previous capability document on the chain, which is granting\n authority to this invocation document.\n In the case of the first delegated capability document, this points\n at the target.\n </dd>\n\n <dt>capabilityDelegation</dt>\n <dd>\n This term serves two purposes:\n <ul>\n <li>\n As a property from which the target supplies the \"initial source\n of authority\" on the chain.\n This holds cryptographic material which it may use to initially\n delegate on the chain (and in some cases which it may use to\n invoke itself as a capability).\n </li>\n <li>\n As the value of a proof's <code>proofPurpose</code> to indicate\n that this proof is intended to grant authority to the <code>controller</code>\n entities on the capability.\n </li>\n </ul>\n </dd>\n </dl>\n </section>\n\n <section id=\"capabilities\">\n <h2>Capabilities</h2>\n\n <p>\n Zcap capabilities are encoded through a chain of linked data\n documents, granting authority to a target, possibly restricted through\n \"caveats\".\n Authority starts with the target (which always has authority to invoke\n itself) and extends to further <code>controller</code> entities along\n the chain.\n Each capability document granting authority must be signed off with a\n proof by an entity which has previously been granted authority on the\n chain.\n Any caveat applied by a parent in the chain applies to its descendants.\n </p>\n\n <div class=\"note\">\n <p>\n The target's json-ld document is a kind of \"special\" capability document\n implicitly granting authority to itself.\n But why?\n Surely in most protocols, such as when objects are sending\n invocations over HTTP POST requests, any target that wants to\n self-modify could do so internally without an explicit invocation\n process.\n But in some systems such as blockchains, there is no \"internal\" state,\n so explicitly doing an invocation to change behavior is still useful.\n </p>\n <p>\n Another reason is that it simplifies the invocation algorithm: as we\n delegate authority to the first non-target entity, we do so using the\n target's cryptographic authority.\n If this authority can be used to grant capabilities, it may as well\n be able to be used to invoke them as well.\n </p>\n </div>\n\n <p>\n Every capability document, except for the target, MUST have:\n </p>\n\n <ul>\n <!-- TODO: What's the right way to say this?\n This sounds very json-ld centric -->\n <li>an associated <code>id</code></li>\n <li>\n <code>parentCapability</code>, which links to the target if this is\n the first delegated capability on the chain, or otherwise links to\n another capability document\n </li>\n <li>\n <!-- TODO: open this up a bit more for more than just \"keys\" -->\n a <code>proof</code> field, which MUST sign the document with\n <a href=\"https://w3c-ccg.github.io/ld-proofs/\">\n Linked Data Proofs</a>\n by cryptographic material which has already been granted authority\n on the chain (either being cryptographic material from the\n <!-- TODO: if #15 ends up with us granting to entities rather than\n specific keys, this will use the capabilityInvocation property\n on both the target and all future granted entities -->\n <code>capabilityDelegation</code> property of the target, or from\n an <code>controller</code> previously granted authority on the chain.\n <!-- TODO: Should this be by any of the authentication material which\n has authority to use this capability, or only the nearest\n invoker on the chain? -->\n </li>\n </ul>\n\n <p>\n Every capability document MUST have:\n </p>\n\n <ul>\n <li>\n <code>controller</code>, which links to one or more instances of\n cryptographic material (such as public keys) being granted authority\n to use this capability\n </li>\n </ul>\n\n <div class=\"note\">\n <p>\n Capabilities are not structured around \"who has access\" to something\n but rather holding onto a capability for a particular use, and in\n order to avoid confused deputy and ambient authority problems,\n in general objects should not hold on to a \"bucket\" of capabilities\n which grant them authority, but hold on to them within specific\n contexts for specific purposes.\n In general, when an object is granted a capability, it is important\n that it know for what specific purpose it has been granted that\n capability so that it does not become confused and use it in the\n wrong scenario.\n This is like how, in computer programs, a procedure called with\n specific arguments understands the meanings of those arguments\n and what they may be used for.\n </p>\n </div>\n\n <!-- TODO: Insert Alyssa's example from the introduction -->\n\n <section id=\"root-capability\">\n <h2>Root Capability</h2>\n <p>\n A root zcap looks like this:\n </p>\n\n <pre class=\"example highlight javascript\">\n{\n \"@context\": \"https://w3id.org/zcap/v1\",\n \"id\": \"urn:zcap:root:https%3A%2F%2Fexample.com%2Ffoo\",\n \"controller\": \"did:key:example\",\n \"invocationTarget\": \"https://example.com/foo\"\n}\n </pre>\n\n <p>\n A root zcap MUST have an `@context` field that is a string with the\n value `https://w3id.org/zcap/v1`. This field makes zcaps JSON-LD\n compatible, but does not mean that any other JSON-LDisms are\n permitted. In other words, zcaps are JSON-based, and the JSON has\n been chosen carefully such that it can be interpreted properly as\n JSON-LD as well. Other JSON-LD representations that deviate from the\n JSON expression of a zcap are not permitted.\n </p>\n\n <p>\n By enabling JSON-LD compatibility, DI proofs (Data Integrity Proofs,\n formerly known as Linked Data proofs) are used instead of JOSE-based\n signatures. This helps keep zcap sizes small by eliminating the need to\n encapsulate zcaps via base64 encoding. This is particularly important\n for expressing capability chains,\n where ancestor zcaps would be base64-encoded N+1 times where N is the\n length or position in the chain. If neither of these approaches were\n used, a novel signature encapsulation mechanism would have to be\n invented to get the same benefits; instead, reuse of existing work is\n preferred.\n </p>\n\n <p>\n Additionally, JSON-LD compatibility enables CBOR-LD to be used\n to express zcaps — further reducing size via semantic compression.\n\n When <a href=\"#invoking-root-capability\">invoking a root zcap</a>,\n a capability invocation proof is added, not to the root zcap itself,\n but rather to another document that is acceptable to an API. This\n means that no additional contexts (especially cryptosuite contexts) ever\n need to be added to a root zcap. Further work on the Data Integrity\n 1.0 spec could alleviate the need for additional cryptosuite\n contexts entirely.]\n </p>\n\n <p>\n A root zcap MUST have an `id` that is a string that expresses a URN.\n This ID can always be dereferenced by the verifier system if it is a\n valid root zcap for a particular endpoint. The ID of a root zcap\n SHOULD <!-- this should become a MUST if it covers all use cases,\n to keep things simple --> have the following format:\n </p>\n\n <pre>\nurn:zcap:root:${encodeURIComponent(invocationTarget)}\n </pre>\n\n <p>\n This format makes it clear that the identifier is for the\n root zcap for the root invocation target, `invocationTarget`.\n </p>\n\n <p>\n A root zcap MUST have an `invocationTarget` that is a string that\n expresses a URI. The invocation target identifies where the zcap may\n be invoked, and identifies the target object for which the root zcap\n expresses authority.\n </p>\n\n <p>\n A root zcap MUST have a `controller` that is a string or an array of\n strings that each express a URI that identifies a controller for the\n root zcap. The controller (or controllers) may take any actions with\n the invocation target (that are supported by the verifier) by\n invoking the root zcap. The controller (or controllers) may create\n <a href=\"#delegated-capability\">delegated zcaps</a>\n from the root zcap.\n </p>\n\n <p>\n Note: A root zcap MUST NOT have any other fields.\n </p>\n\n <p>\n A root zcap can be invoked by referencing only its ID because the\n verifier can (and MUST) always dereference the zcap locally using a\n trusted dereferencing mechanism. This is because a root zcap does not\n have a capability delegation proof; it is the root of trust for a\n capability chain.\n </p>\n\n <section id=\"invoking-root-capability\">\n <h2>Invoking a Root Zcap</h2>\n\n <p>\n There can be multiple ways to invoke a root zcap.\n These include:\n </p>\n <ul>\n <li>\n <a href=\"#invocation-http-request\">Invocation HTTP requests</a>, i.e. attaching `capability-invocation` and `signature` headers to an http request\n </li>\n <li>\n <a href=\"#invocation-json-proof\">Invocation JSON objects</a>, i.e. attaching a `capabilityInvocation` proof to a object's `proof` set\n </li>\n </ul>\n\n <p>\n The verifier will decide which of these methods is acceptable.\n </p>\n </section>\n\n <section id=\"dereferencing-root-capability\">\n <h2>Dereferencing a Root Capability on a Verifier System</h2>\n\n <p>\n It is expected that only verification systems will dereference root\n zcaps from their IDs. One model for new HTTP APIs is to store a\n controller value with every resource at the base of a hierarchy,\n for instance, store controller `X` for the collection\n `https://foo.example/collections/123`. When the root zcap for this\n collection is invoked or referenced via a delegated zcap invocation,\n the verifier can look up the `controller` property (or receive it from\n another system in some kind of decentralized setup) for that\n resource and include it in a \"dynamically dereferenced\" root zcap.\n In other words, the verifier sees the root zcap ID\n `urn:zcap:root:{encodeURIComponent(https://foo.example/collections/123)}`,\n and dynamically converts that (after looking up its controller) into:\n </p>\n\n <pre class=\"example highlight javascript\">\n{\n \"@context\": \"https://w3id.org/zcap/v1\",\n \"id\": \"urn:zcap:root:https%3A%2F%2Ffoo.example%2Fcollections%2F123\",\n // populated via a database or external system call\n \"controller\": \"did:key:example\",\n \"invocationTarget\": \"https://foo.example/collections/123\"\n}\n </pre>\n\n </section>\n </section>\n\n <section id=\"delegated-capability\">\n <h2>Delegated Capability</h2>\n\n <p>\n A delegated zcap looks like this:\n </p>\n\n <pre class=\"example highlight javascript\">\n{\n \"@context\": [\n \"https://w3id.org/zcap/v1\",\n \"https://w3id.org/security/data-integrity/v2\"\n ],\n \"id\": \"urn:uuid:cdc77118-6bfa-11ec-aceb-10bf48838a41\",\n \"parentCapability\": \"urn:zcap:root:https%3A%2F%2Fexample.com%2Ffoo\",\n \"controller\": \"did:key:example\",\n \"invocationTarget\": \"https://example.com/foo\",\n \"expires\": \"2021-11-03T18:33:51Z\",\n \"allowedAction\": [\n \"write\",\n \"read\"\n ],\n \"proof\": {\n \"type\": \"DataIntegrityProof\",\n \"cryptosuite\": \"eddsa-jcs-2022\",\n \"created\": \"2021-10-27T18:33:51Z\",\n \"capabilityChain\": [\n \"urn:zcap:root:https%3A%2F%2Fexample.com%2Ffoo\"\n ],\n \"proofPurpose\": \"capabilityDelegation\",\n \"proofValue\": \"z3t9BCQyF21MDVYmLKc9zbLreqx4wBtQnUsd5aqyoWS5FfhapRz7QjPNLcgKAornUVmJR4ZjbGpuxRFnffxX1ZjtF\",\n \"verificationMethod\": \"did:key:z6MkfWKcvBiKCfNgz5UUGseNt37t4dguEvFgJ9XvX2UV6zB9#z6MkfWKcvBiKCfNgz5UUGseNt37t4dguEvFgJ9XvX2UV6zB9\"\n }\n}\n </pre>\n\n <p>\n A delegated zcap is different from a root zcap primarily in that it\n has a `parentCapability`, an expiration date-time, and a capability\n delegation proof (found in proof). It is also different from a root\n zcap in that all delegated zcaps in a chain must be fully provided to the verifier when invoking a\n delegated zcap, so that the verifier is not required to dereference\n them other than via the provided chain. <i><b>Note:</b> A verifier may still\n need to query a database for delegated zcaps to perform\n revocation checks by ID. However, a verifier MUST NOT be required to perform\n network requests or database queries to dereference delegated zcaps\n by ID when verifying the capability chain, prior to inspecting it for potential revocations.</i>\n </p>\n\n <p>\n A delegated zcap MUST have an `@context` field with an array where the\n first value is the zcapld context `https://w3id.org/zcap/v1`,\n and any subsequent values identify context(s) used to define vocabulary terms used in the capability\n delegation proof.\n </p>\n\n <p>\n A delegated zcap MUST have an `id` that is a string that expresses a\n URI. The id SHOULD have the format:\n </p>\n\n <pre>\nurn:uuid:{uuid}\n </pre>\n\n <p>\n Using this format enables CBOR-LD to perform compression on the ID\n value, and reduces correlation risk by making the ID semantically\n opaque.\n </p>\n\n <p>\n A delegated zcap MUST have a `parentCapability` that is a string that\n expresses the ID of the parent zcap. The parent zcap may be another\n delegated zcap or the root zcap. A verifier MUST ensure that a\n delegated zcap was created by a controller of its parent capability\n by checking its capability delegation proof.\n </p>\n\n <p>\n A delegated zcap can only be invoked by submitting the entire zcap.\n </p>\n\n <p>\n A delegated zcap MUST have a capability delegation proof.\n A capability delegation proof MUST have a `capabilityChain` property whose value is a <dfn>capability ancestors array</dfn>.\n A [=capability ancestors array=] MUST be an array that includes the root\n zcap using its ID (i.e., by reference only, not embedded) and every\n other delegated zcap in its ancestry must be referenced by ID except\n for the parent delegated zcap, which MUST be fully embedded. This\n ensures that delegated zcaps are of minimal size (other delegated\n zcaps in the chain are never repeated) and that every delegated zcap\n can be dereferenced directly from the chain without ever having to hit\n a network resource or similar. The capability delegation chain is\n ordered; the first entry MUST be the root zcap's ID and any other\n entries must be in the order of delegation from least recent to most\n recent.\n </p>\n\n <p>\n A verifier MUST limit the length of the capability chain to prevent\n long chain attacks. A verifier SHOULD limit the length of the\n capability chain to 10. <!-- exposition on why 10 / link to security\n section]. -->\n </p>\n\n <p>\n A root zcap MUST have an `invocationTarget` that is a string that\n expresses a URI. The invocation target identifies where the zcap may\n be invoked. A verifier MUST ensure that the `invocationTarget` either\n matches the `invocationTarget` in the parent capability or, if\n invocation target attenuation <!-- TODO: link --> is permitted, that it has the\n `invocationTarget` from the parent capability as a prefix. A prefix is\n defined as a base URI and parent path (and optional query) (i.e.,\n `/`-delimited and `?`/`&`-delimited) <!-- TODO: more rigorous definition -->\n </p>\n\n <p>\n A delegated zcap MUST have a `controller` that is a string or an array\n of strings that each express a URI that identifies a controller for\n the delegated zcap. The controller (or controllers) may take any\n allowed <a href=\"#actions\">actions</a> with the invocation target (that are supported\n by the verifier) by invoking the delegated zcap. The controller (or\n controllers) may create delegated zcaps from the delegated zcap.\n <i><b>Note:</b> As with other data model sections in W3C specs, every property\n of a zcap should be called out in its own subsection along with the\n rules for the property.</i>\n </p>\n\n <p>\n A delegated zcap MUST have an `expires` field that expresses an XSD\n date-time <i><b>Note:</b> The JavaScript `new Date().toISOString()` code can\n produce such a date representation, though it is preferred to remove\n millisecond precision via `new Date().toISOString().slice(0, -5) +\n 'Z'`.</i>\n </p>\n\n <p>\n A verifier MUST ensure that an invoked delegated zcap has not expired.\n A verifier MUST ensure that a delegated zcap's expiration date-time is\n not less restrictive than its parent capability's expiration\n date-time, if present. <i><b>Note:</b> a root zcap does not have an expiration\n date-time.</i>\n </p>\n\n <p>\n A verifier SHOULD ensure that an invoked delegated zcap does not have\n an expiration date-time that is more than three months in the future.\n <!-- TODO: explain why 3 months -->\n This is because a verifier\n MUST store revoked zcaps until they expire, to\n <!-- TODO: add revocation section and link to it -->\n prevent their use. A delegated zcap with an expiration date that is\n unreasonably far into the future will have to be stored for an\n unreasonable period of time to prevent its invocation. There are\n other mitigation strategies here, such as considering all zcaps\n delegated from a particular controller as revoked, or full key\n revocation.\n </p>\n\n <p>\n Delegated zcaps MUST have expiration date-times to support good\n security hygiene practices and because zcaps support decentralized\n delegation. In order to revoke a zcap, it must be submitted to the\n verifier's revocation endpoint for the associated invocation target.\n If a delegated zcap has been lost or misplaced, it MUST eventually\n expire to avoid undesirable access.\n </p>\n\n <p>\n A delegated zcap MAY have an `allowedAction` field that is a string or\n an array of strings that each express an action that the controller of\n the zcap may take when invoking the capability. A verifier MUST ensure\n that the `allowedAction` field in a delegated zcap is not less\n restrictive than the parent's capability, if present.\n </p>\n\n <p>\n A delegated zcap MUST have a `proof` field that is an object or an\n array of objects that each express a DI proof. At least one of these\n proofs MUST be a zcap capability delegation proof.\n <!-- TODO: more details on this proof -->\n </p>\n\n <p>\n A capability delegator (one who creates a delegated zcap) may\n attenuate authority by setting a more restrictive expiration\n date-time, a more restrictive invocation target (via URL path- or\n query-based attenuation), or a greater limit on the allowed actions. Taken\n together, the API that a verifier manages access is expected to have\n the flexibility required to model all desired authorization models.\n </p>\n\n\n\n <section id=\"delegated-capability-attenuation\">\n <h2>URL Path- or Query-based Attenuation</h2>\n\n <p>\n Note: The `@context` / vocab-based caveats have been removed and replaced with:\n </p>\n\n <p>\n A verifier will accept delegations (and invocations) where a suffix\n has been added to the parent zcap's invocation target (invoked zcap's\n invocation target). The suffix MUST start with `/` or `?` if the\n invocation target prefix has no `?`, and with `&` otherwise. This allows for\n fully customizable attenuations via HTTP API path and query\n parameters. For example, a zcap that can be invoked at\n `https://foo.example/bars/123` can be delegated with an attenuation\n such that the delegated zcap has an invocation target of\n `https://foo.example/bars/123/bazzes/456`. This could be further\n delegated and attenuated with a zcap with an invocation target of\n `https://foo.example/bars/123/bazzes/456?day=tuesday` and then again\n with `https://foo.example/bars/123/bazzes/456?day=tuesday&hour=12`.\n </p>\n </section>\n\n <section id=\"invoke-delegate-capability\">\n <h2>\n Invoking a Delegated Zcap\n </h2>\n\n <p>\n Just like <a href=\"#invoking-root-capability\">with root zcaps</a>, there can be multiple ways to invoke a\n delegated zcap.\n </p>\n\n </section>\n </section>\n\n <section id=\"delegation\">\n <h2>Delegation through Capability Chains</h2>\n <p>\n A capability document that is not the target MUST also have a\n <code>parentCapability</code> property which either points at the\n target or another capability document.\n A series of capability chained together in this way is called a\n \"capability chain\" and is how delegation of capabilities are\n handled in zcaps.\n New keys MAY be granted authority to use this capability through\n the associated <code>controller</code> property.\n </p>\n </section>\n\n <section id=\"caveats\">\n <h2>Caveats</h2>\n <p>\n Every capability document MAY add restrictions on the way the\n capability may be used by adding to the <code>caveat</code> property.\n Capabilities inherit the restrictions from all <code>caveat</code>\n properties of their parents, and MAY add new caveats in addition to\n those of their parents.\n </p>\n <p>\n The meaning of caveats are determined by their <code>type</code>\n and whatever other properties they have.\n Due to the way they are interpreted at invocation type by the target,\n some mutual understanding of terminology must be understood between\n the entity adding a caveat and the target evaluating (or any other\n parties observing) the invocation.\n </p>\n </section>\n\n <section id=\"capabilities-vs-ACLs\">\n <h2>Capabilities vs. Access Control Lists</h2>\n <p>\n One of the first questions that is usually asked about using\n Object Capabilities for authorization is: \"How are Capabilities\n different from Access Control Lists?\". Fundamentally, Access Control\n Lists are about <em>authority by identity</em> whereas\n Object Capabilities are about <em>authority by possession</em>.\n </p>\n\n <p>\n Authority by identity is the process of giving access to a resource\n to a specific entity based on their identity. These processes\n typically ask the question: \"Who are you?\"\n </p>\n\n <p>\n Authority by possession is the process of giving access to a resource\n to any entity that possesses something, like a key. These processes\n typically ask the question: \"Do you have a key that fits this lock?\"\n </p>\n\n <p>\n This document doesn't explain why Access Control Lists lead to\n a variety of security issues or why Object Capabilities provide\n stronger security guarantees. For those that would like to\n learn more about these topics,\n <a href=\"http://srl.cs.jhu.edu/pubs/SRL2003-02.pdf\">Capability Myths Demolished</a>\n and\n <a href=\"http://waterken.sourceforge.net/aclsdont/current.pdf\">ACLs Don't</a>\n provide a deeper exploration into the benefits of Object Capabilities.\n </p>\n </section>\n\n <!-- TODO: move this to security considerations section:\n\n Unlike access control lists, the focus of capabilities is about\n what action is being performed by who is \"holding\" a\n capability they have authority to use rather than checking who\n is performing a specific action every time an action is\n performed.\n -->\n </p>\n </section>\n\n <section id=\"invocation\">\n <h2>Invocation</h2>\n\n <p>\n A capability may be enacted through the process of invocation.\n In the context of zcaps, an invocation consists of a linked data\n object which MUST have a <code>proof</code> property with a value\n containing:\n </p>\n\n <ul>\n <li>\n a <code>proofPurpose</code> of <code>capabilityInvocation</code>\n </li>\n <li>\n a <code>capability</code> property which links to the\n capability document that grants authority to invoke this capability\n </li>\n <li>\n the proof must validate against cryptographic material\n granted authority by the <code>controller</code> field from the\n capability chain.\n </li>\n </ul>\n\n <p>\n An invocation SHOULD have an <code>id</code> (which may also serve as a\n nonce).\n Any other properties are considered arguments to the invocation.\n </p>\n\n <p>\n Each capability document accrues granted authority in the chain, which\n is used to both authorize further capability delegation and may be used\n to invoke the capability chain.\n The capability document that is invoked's chain is recursively traversed\n up along the <code>parentCapability</code> document until the target is\n found (the root document that has no <code>parentCapability</code>\n property).\n The target's <code>capabilityDelegation</code> cryptographic material is\n marked in the initial set of authority.\n The capability chain is then traversed from this root target back down\n through each delegated capability all the way to the invoked capability\n document leaf, validating while restricting and delegating authority:\n </p>\n\n <li>\n <ul>\n The <code>proof</code> field of this capability document is checked for a\n valid proof with a <code>proofPurpose</code> of\n <code>capabilityDelegation</code> where the <code>creator</code> of the\n proof is cryptographic material in the currently authorized set.\n </ul>\n <ul>\n The caveats of this capability document are checked for validity.\n </ul>\n <ul>\n The cryptographic material on the <code>controller</code> field is added\n to the currently authorized set.\n </ul>\n <ul>\n We traverse to the next document downwards towards the leaf, repeating\n this process until we are back at the leaf again.\n </ul>\n </li>\n\n <p>\n At this point, the invocation is considered valid and any relevant\n action may be performed.\n (This does not guarantee that a specific result will occur, merely that\n the invocation itself is valid; a invocationTarget could in evaluating\n the invocation encounter invalid input and return or raise an error,\n for instance.)\n </p>\n\n <div class=\"note\">\n <p>\n Since invocations are themselves linked data documents, it is\n possible for an invocation to refer to an invocation as an argument.\n For this reason it is critical that mechanisms for accepting\n invocations be sure which invocation is being performed.\n For example, a mechanism that accepts authorization capabilities as\n JSON-LD documents will likely have no trouble telling which\n invocation is being performed since that will be the \"top\"\n of the framed document.\n However, a mechanism which accepted N-Quads would need additional\n information supplied perhaps in the headers in order to be able\n to determine the \"root\" of the invocation.\n </p>\n </div>\n\n <section id=\"invocation-http-request\">\n <h2>Invocation HTTP Request</h2>\n <section id=\"invocation-http-signature\">\n <h3>Invocation HTTP Signature</h3>\n\n <p>\n When invoking a root zcap using an HTTP signature, a\n capability-invocation header must be included that identifies the\n root zcap by ID (via an `id` parameter) and the capability action\n that is being invoked (via an `action` parameter). The request URL\n identifies the intended invocation target, which must either match\n the invocation target in the root zcap, or, if the verifier allows\n it, have the root zcap's invocation target as a prefix. The\n capability action must be an action that is expected (supported) by\n the verifier at the request URL. The capability action SHOULD be\n read or write. The key used to create the HTTP signature must be either\n 1) the private key paired with a verification method that matches\n the controller of the root zcap or 2) a verification method that is\n controlled by the controller of the root zcap — and authorized for the\n purpose of `capabilityInvocation`.\n </p>\n\n <p>\n When invoking a delegated zcap using an HTTP signature, a\n capability-invocation header must be included that includes the full\n delegated zcap in a `capability` parameter by serializing it to JSON,\n gzipping the result, and then base64url-encoding the gzipped JSON.\n </p>\n\n </section>\n\n <section id=\"invocation-http-example\">\n <h4>Example Invocation HTTP Requests</h4>\n\n <figure id=\"fig-invocation-http-example-basic\">\n <figcaption>\n This is an example of how a capability invocation request may be serialized as message/http.\n </figcaption>\n <pre class=\"example http\" title=\"Invocation HTTP Request\">\nPOST /api/v1/example HTTP/1.1\nHost: example.com\nDate: Tue, 25 Aug 2026 00:00:00 GMT\nContent-Type: application/json\nCapability-Invocation: zcap capability={base64url(gzip(json(capability)))}\nContent-Digest: sha-256=:y6p4T1s616oH+n04bZ9NzPzqB2qR+B/T3V7V9XN6b4Y=:\nSignature-Input: zcap=(\"@method\" \"@path\" \"capability-invocation\" \"content-digest\" \"content-type\");alg=\"ed25519\";created=1798294620;keyid=\"did:example:alice#key-1\"\nSignature: zcap=:m28+dfHk1Pq6VvKxFxX9Q9zNz98bX5cKldP1M0zNzM3NzUzNzdXNzr1PzM3NzUzNzUzNzr1PzM3NzUzNzUzNzM3NzA==:\n\n{\"type\":\"ExampleApiAction\"}\n\n </pre>\n </figure>\n\n <figure id=\"fig-invocation-http-example-with-trailers\">\n <figcaption>\n This is an example of how a capability invocation request may be serialized as message/http using trailing headers.\n This enables deferral of generating a digest and signature until after all data has been transmitted.\n </figcaption>\n <pre class=\"example http\" title=\"Invocation HTTP Request with Trailing Headers\">\nPOST /api/v1/example HTTP/1.1\nHost: example.com\nDate: Tue, 25 Aug 2026 00:00:00 GMT\nContent-Type: application/json\nTE: trailers\nTrailer: Capability-Invocation, Content-Digest, Signature-Input, Signature\nTransfer-Encoding: chunked\n\n1B\n{\"type\":\"ExampleApiAction\"}\n0\nCapability-Invocation: zcap capability={base64url(gzip(json(capability)))}\nContent-Digest: sha-256=:y6p4T1s616oH+n04bZ9NzPzqB2qR+B/T3V7V9XN6b4Y=:\nSignature-Input: zcap=(\"@method\" \"@path\" \"capability-invocation\" \"content-digest\" \"content-type\");alg=\"ed25519\";created=1798294620;keyid=\"did:example:alice#key-1\"\nSignature: zcap=:m28+dfHk1Pq6VvKxFxX9Q9zNz98bX5cKldP1M0zNzM3NzUzNzdXNzr1PzM3NzUzNzUzNzr1PzM3NzUzNzUzNzM3NzA==:\n\n </pre>\n </figure>\n </section>\n\n\n </section>\n\n <section id=\"invocation-json\">\n <h2>Invocation JSON</h2>\n\n <p>\n HTTP isn't always the best choice for representing invocations.\n Some peers may wish to wish to represent the invocation proofs in pure JSON instead of HTTP Signatures,\n e.g. because they intend to request invocation over a protocol other than HTTP.\n For this, there is a standard representation of zcap invocations as JSON objects.\n </p>\n\n <section id=\"invocation-json-proof\">\n <h3>Invocation JSON `proof`</h3>\n\n <p>\n When invoking using a DI proof, a capability invocation proof must\n be attached to a document that is acceptable by the API, as\n defined by the specific API being accessed. The capability\n invocation proof MUST include the intended `invocationTarget`, the\n root zcap ID in the `capability` property, and the action to be taken\n in the `capabilityAction` property. The same controller rules apply\n as in <a href=\"#invocation-http-signature\">the HTTP signature case</a>.\n </p>\n\n <p>\n When invoking a delegated capability using a DI proof,\n the capability property must express the full delegated zcap.\n </p>\n\n\n <figure id=\"invocation-json-example\">\n <figcaption>\n An example of how a capability invocation may be serialized as application/json.\n </figcaption>\n <pre\n class=\"example json\"\n title=\"Capability Invocation JSON\"\n >\n{\n \"id\": \"urn:uuid:394a2467-bd2e-4d39-9e42-d1881737f82e\",\n \"proof\": {\n \"type\": \"DataIntegrityProof\",\n \"proofPurpose\": \"capabilityInvocation\",\n \"cryptosuite\": \"eddsa-jcs-2022\",\n \"invocationTarget\": \"https://whatacar.example/a-fancy-car\",\n \"capabilityAction\": \"Drive\",\n \"capability\": {\n \"id\": \"https://whatacar.example/a-fancy-car/proc/7a397d7b\",\n \"parentCapability\": \"urn:zcap:root:https%3A%2F%2Fwhatacar.example%2Fa-fancy-car\",\n \"controller\": \"https://social.example/alyssa#key-for-car\",\n \"invocationTarget\": \"https://whatacar.example/a-fancy-car\",\n \"proof\": {\n \"type\": \"DataIntegrityProof\",\n \"created\": \"2018-02-13T21:26:08Z\",\n \"cryptosuite\": \"eddsa-jcs-2022\",\n \"capabilityChain\": [\n \"urn:zcap:root:https%3A%2F%2Fwhatacar.example%2Fa-fancy-car\"\n ],\n \"proofPurpose\": \"capabilityDelegation\",\n \"proofValue\": \"z2YwC8z3ap7yx1nZYCg4L3j3ApHsF8kgPdSb5xoS1VR7vPG3F561B52hYnQF9iseabecm3ijx4K1FBTQsCZahKZme\",\n \"verificationMethod\": \"https://example.com/i/alice/keys/1\"\n },\n \"@context\": [\n \"https://w3id.org/zcap/v1\",\n \"https://w3id.org/security/data-integrity/v2\",\n \"https://autopower.example/\"\n ]\n },\n \"created\": \"2016-02-08T17:13:48Z\",\n \"verificationMethod\": \"https://social.example/alyssa/#key-for-car\",\n \"proofValue\": \"...\"\n },\n \"@context\": [\n \"https://w3id.org/zcap/v1\",\n \"https://w3id.org/security/data-integrity/v2\",\n \"https://autopower.example/\"\n ]\n}\n </pre>\n </figure>\n\n </section>\n </section>\n\n <section id=\"actions\">\n <h2>Actions</h2>\n\n <p>\n Actions are a common way to direct behavior of an invocation.\n Targets are free to choose their own mechanisms for directing\n behavior, but MAY support the <code>action</code> property on\n invocations as one common behavioral direction technique.\n The <code>action</code> property points to a URI as a form of\n vocabulary to determine which action is being performed.\n For example, a capability to a file storage system may allow\n for both reading and writing files, and a user could choose\n to set the <code>action</code> to\n <code>https://datastore.example/WriteFile</code>\n as an argument on their invocation.\n </p>\n\n <!-- TODO: Caveats which restrict to specific actions are fairly\n common. Do we want to define such a caveat in this document? -->\n\n </section>\n </section>\n\n <section class=\"informative\" id=\"zcap-v1-context\">\n <h2>The zcap v1 JSON-LD Context</h2>\n\n <p>\n Every zcap has an <code>@context</code> property whose value is, or\n begins with, the URL <code>https://w3id.org/zcap/v1</code>, as required\n by <a href=\"#root-capability\">Root Capability</a> and\n <a href=\"#delegated-capability\">Delegated Capability</a>.\n That URL identifies the zcap v1 JSON-LD Context.\n </p>\n\n <p>\n The hexadecimal encoded SHA2-256 digest value of the zcap v1 context\n file is\n <code>4c0bd364bf3a5215779c0b636e14bcdf1d6818dae002bc7580237bcf8d2a72e0</code>.\n It is possible to confirm the cryptographic digest above by running the\n following command from a modern Unix command line interface:\n <code>curl -sL https://w3id.org/zcap/v1 | openssl dgst -sha256</code>.\n </p>\n\n <p>\n A copy of the zcap v1 context file having the digest value above is\n published alongside this document at\n <a href=\"contexts/zcap-v1.jsonld\">contexts/zcap-v1.jsonld</a>.\n </p>\n </section>\n\n <section id=\"conformance\">\n <!--\n ReSpec will insert here something like:\n > As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.\n >\n > The key words MAY, MUST, MUST NOT, and SHOULD in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.\n -->\n </section>\n\n <!-- TODO: explore whether composition is fully supported by the\n current state of this document\n -->\n\n <section class=\"appendix informative\" id=\"relationship-to-vc\">\n <h2>Relationship to Verifiable Credentials</h2>\n\n <p>\n The\n <a href=\"https://www.w3.org/TR/verifiable-claims-data-model/\">\n Verifiable Credentials Data Model</a>\n provides a powerful vocabulary for correlating information and\n presenting correlated information in a secure way.\n This can be used to make claims about some subject, to present\n credential certifying you are qualified to do some thing, or so on.\n This is useful for gathering and presenting information that can\n be reasoned about.\n Indeed, this maps nicely to \"the real world\", as humans tend to be\n \"correlation/reasoning machines\".\n For example, Eva Lu Ator is hoping to hire a system administrator and\n may check for a college diploma, past work history, or recommendations\n from known entities considered qualified to judge competency to fulfill\n the role, and all of these can be modeled nicely with the Verifiable\n Credentials Data Model.\n </p>\n\n <p>\n Thus it may be tempting to design a system in which a credential\n is presented in order to permit or forbid access to some resource.\n Unfortunately, associating \"who is authorized to do what\" leads us back\n to all the problems of access control lists,\n <a href=\"capabilities-are-safer\">which we would like to avoid</a>.\n When returning to our hiring a system administrator example it is\n easy to imagine how, upon hiring Alice as as a system administrator,\n Eva would hand Alice a capability to begin administrating her systems.\n But in considering the previous step where Eva contemplates\n <i>whether or not to hand Alice that capability</i>\n seems to pull us right back to correlating information about Alice's\n identity.\n (What is Alice's educational background? What is Alice's prior work\n experience?)\n </p>\n\n <p>\n We seem to be in a conundrum.\n Claims and credentials are forms of correlation that allow us to reason\n about an entity in our squishy human world, but are unsafe when used as\n mechanisms to authorize some event to occur within a system.\n Capabilities are a safe mechanism to model the flow of authority through\n a system, but there are times when capabilities have not been granted\n and we need to make a \"judgement call\" by correlating information about\n that entity.\n What should we do?\n </p>\n\n <p>\n To pose the question is to see the answer: the right approach is to use\n each system for what it does best.\n Use correlation (Verifiable Credentials) in a reasoning system (most\n commonly human reasoning) as a path to make judgements about whether to\n hand an entity a specific set of initial capabilities.\n Use capabilities (zcaps) as the mechanism to grant and exercise\n authority through computing systems.\n To return to our system administrator example, when Alice applies for the\n job, she submits a series of credentials about her prior work history\n and degree, and Eva is able to verify that it is Alice's former\n employers and university which have made these claims.\n Deciding that Alice is fit for the job, Eva hands Alice her initial\n capability which grants her authority to administrate the systems in\n question (with a caveat that allows Eva to revoke that authority at a\n future date, if appropriate).\n Alice uses that capability as the initial entry point into\n administrating the system.\n </p>\n </section>\n\n <section class=\"appendix informative\" id=\"handling-abuse\">\n <h2>Handling abuse</h2>\n\n <p>\n The previous section discussed cases in which correlation (particularly\n through Verifiable Credentials) is used to grant an initial set of\n capabilities.\n This section discusses how correlation may be used to revoke\n capabilities under certain circumstances, and steps that should be\n taken to ensure this is done safely.\n </p>\n\n <p>\n Capability systems focus on what authority grants that an operation may\n be performed, not on who is performing the action.\n In some object capability systems (such as many object capability\n programming languages) it is not even possible to see what entity is\n invoking a capability.\n In the case of zcaps, it is always possible to inspect an invocation\n to check which authentication material authorized to invoke the\n capability is being used in the invocation, and this may permit\n checking a certain amount of \"who\" is performing the action, but to\n focus on the \"who\" rather than the source of authority would\n <a href=\"capabilities-are-safer\">\n bring us back to the dangers of Access Control Lists</a>.\n </p>\n\n <p>\n Nonetheless, there comes a time when correlating information about\n usage of a resource becomes critical, and this is in mitigating abuse.\n Even traditional capability systems, in developing solutions to this\n problem, develop techniques for correlating information about \"who\"\n has performed an action.\n (For example,\n <a href=\"http://www.erights.org/elib/capability/horton/\">Horton</a>\n is one such system for E, though as previously stated,\n such information can be gleaned already by looking at the invocation\n and capability chain documents in zcaps.)\n The key to permit detecting and mitigating abuse safely in a capability\n based environment is to treat correlation of who is using a service\n not as something that is used per-invocation, but as something to be\n reasoned about to possibly revoke authority.\n (Astute readers may observe that between the previous section and this\n section we have defined safe ways to use correlation in conjunction\n with capabilities: as the entry point and possible termination point,\n with capabilities powering the machine in-between.)\n </p>\n\n <p>\n For example, Alice has granted capabilities (with caveats that permit\n revocation) to a number of users access to run programs on the systems\n she is administrating, but someone is using their capability to abuse\n the system.\n The system itself performs the invocations as the users call them,\n but Alice, or a program Alice runs, is able to analyze a log of past\n invocations called.\n Having finished the analysis, Alice realizes that the abuse is coming\n from the invocation of a capability granted to some of Mallet's\n authentication material, and Alice revokes that capability.\n </p>\n </section>\n\n <section class=\"appendix informative\" id=\"changelog\"\n data-include=\"CHANGELOG.md\"\n data-include-format=\"markdown\">\n <!--\n This section's content comes from CHANGELOG.md, the canonical record of\n changes that have already been made to this document.\n ReSpec fetches it over HTTP, so this section is empty when index.html is\n opened via a file:// URL instead of a web server.\n -->\n </section>\n\n <section class=\"appendix informative\" id=\"work-plan\">\n <h2>Work Plan</h2>\n <p>\n This is a non-binding plan of how the authors intend this document to develop.\n Changes that have already been made are recorded in the\n <a href=\"#changelog\">Change Log</a>.\n </p>\n\n <section id=\"milestones\">\n <h3>Milestones</h3>\n <p>\n These are the releases the authors intend to work on next.\n </p>\n\n <section id=\"milestone-v0.4.0\">\n <h4>v0.4.0: Improve Readability, Update Examples</h4>\n\n <p>\n The goals of the release are\n to ship some low cost high impact readability improvements,\n ensure examples conform to specified behaviors,\n move quickly and safely by prioritizing only non-normative changes,\n and to begin planning more substantial normative changes in the <a href=\"#backlog\">backlog</a>\n for v0.5.0 and beyond.\n </p>\n\n <p>\n The changes made for this milestone are listed in the\n <a href=\"#changelog\">Change Log</a>.\n </p>\n </section>\n\n <section id=\"milestone-v0.5.0\">\n <h4>v0.5.0</h4>\n <p>\n This milestone is not yet planned. Once <a href=\"#milestone-v0.4.0\">v0.4</a> is done, it will be planned from issues in the <a href=\"#backlog\">backlog</a> and issue tracker.\n </p>\n </section>\n </section>\n\n <section id=\"backlog\">\n <h3>Backlog</h3>\n <p>\n These issues may be added to <a href=\"#milestones\">milestones</a>.\n They may also be removed from the backlog.\n Generally, they are listed in priority order.\n </p>\n\n <section>\n <h4>\n Clarify delegated capability `proof` property\n </h4>\n\n <p>Acceptance Criteria:</p>\n <ul>\n <li>\n <div>\n Answer questions about these requirements\n <blockquote>\n A delegated zcap MUST have a proof field that is an object or an array of objects that each express a DI proof.\n At least one of these proofs MUST be a zcap capability delegation proof.\n </blockquote>\n </div>\n <ul>\n <li>What is meant by \"each express a DI proof\"? Clarify or remove that clause.</li>\n <li>Are non-DataIntegrityProof values allowed?</li>\n <li>What is meant by \"MUST be a zcap capability delegation proof\"?</li>\n </ul>\n </li>\n <li>\n Add a normative reference to\n <a href=\"https://www.w3.org/TR/vc-data-integrity-1.1/\">\n vc-data-integrity-1.1\n </a>.\n </li>\n </ul>\n </section>\n\n <section>\n <h4>Specify algorithms for delegation proof</h4>\n <p>Acceptance Criteria:</p>\n <ul>\n <li>\n Specify an algorithm to add a `capabilityDelegation` proof to a delegated capability.\n This should be similar to\n <a href=\"https://www.w3.org/TR/vc-data-integrity/#add-proof\">\n Add Proof in VC Data Integrity.\n </a>\n </li>\n <li>\n Specify an algorithm to verify a `capabilityDelegation` proof on a delegated capability.\n This should be similar to\n <a href=\"https://www.w3.org/TR/vc-data-integrity/#verify-proof\">\n Verify Proof in VC Data Integrity\n </a>\n (but for zcap delegations).\n </li>\n </ul>\n </section>\n\n <section>\n <h4>Specify algorithms for invocation HTTP proof</h4>\n <p>Acceptance Criteria:</p>\n <ul>\n <li>\n Specify algorithm to create an Invocation HTTP Request from a delegated capability.\n </li>\n <li>\n Specify an algorithm to add a proof of invocation to a\n <a href=\"#invocation-http-request\">invocation HTTP request</a>.\n This should be similar to\n <a href=\"https://www.w3.org/TR/vc-data-integrity/#add-proof\">\n Add Proof in VC Data Integrity.\n </a>\n </li>\n </ul>\n </section>\n\n <section>\n <h4>Specify algorithms for invocation JSON proof</h4>\n <p>Acceptance Criteria:</p>\n <ul>\n <li>\n Specify an algorithm to add a `capabilityInvocation` proof to\n <a href=\"#invocation-json\">invocation JSON</a>.\n This should be similar to\n <a href=\"https://www.w3.org/TR/vc-data-integrity/#add-proof\">\n Add Proof in VC Data Integrity.\n </a>\n </li>\n <li>\n Specify an algorithm to verify a `capabilityInvocation` proof on an invocation JSON.\n <a href=\"#invocation-json\">invocation JSON</a>.\n This should be similar to\n <a href=\"https://www.w3.org/TR/vc-data-integrity/#verify-proof\">\n Verify Proof in VC Data Integrity.\n </a>\n </li>\n </ul>\n </section>\n\n <section>\n <h4>Other Issues</h4>\n\n <div class=\"issue\">\n v0.3 was published in 2022. Since then, some implementors have made changes to their implementations based on their experience in production, which may be incorporated into this spec. If this experience can be described, and the changes articulated, they may be incorporated into this document.\n </div>\n\n <div class=\"issue\"\n title=\"Detail validation algorithm\"\n >\n <p>\n Detail algorithm for validation process:\n https://github.com/digitalbazaar/zcapld/blob/4386185f784f552d6eaeb2c3c82959cb2e09762e/lib/CapabilityProofPurpose.js#L85\n </p> \n </div>\n\n <div class=\"issue\"\n title=\"Add Revocation Section\"\n >\n <p>\n Explain revocation behavior in a new section.\n </p>\n <p>\n Wishlist\n </p>\n <ul>\n <li>\n Add a named section for other sections to link to for an overview of revocation.\n </li>\n <li>\n Detail what verifiers MUST/SHOULD do to provide revocation endpoints for zcaps.\n </li>\n <li>\n A root invocation\n target SHOULD have a `/zcaps/revocations` subpath, where a root zcap of\n `urn:zcap:root:{the revocations path/the zcap ID to revoke}` can be\n invoked. The verifier SHOULD set the controllers for that root\n zcap to all controllers in the (to be revoked) zcap's chain so\n that any controller in the chain can revoke the zcap.\n </li>\n <li>\n Any controller in the chain of a\n delegated zcap may post that zcap to:\n `{rootInvocationTarget}/zcaps/revocations/{zcapToRevokeId}`\n using the\n root zcap: `urn:zcap:root:encodeURIComponent(\"{rootInvocationTarget}/zcaps/revocations/{zcapToRevokeId}\")`\n to revoke.\n Example: https://github.com/digitalbazaar/ezcap-express/blob/main/lib/revoke.js\n </li>\n <li>\n Link to example server-side revocation implementations like\n <a href=\"https://github.com/digitalbazaar/ezcap-express/blob/main/lib/revoke.js\">\n digitalbazaar's ezcap-express\n </a>\n .\n </li>\n </ul>\n </div>\n\n <div\n class=\"issue\"\n data-title=\"Long Examples are Hard to Read\"\n >\n <p>\n Examples with long `capabilityChain` values can get very long.\n It's nice for authors to maintain complete, conformant examples in one place,\n but some readers might not like having to scroll so much to scroll past each example.\n </p>\n <p>\n We should consider mitigating this by using a respec plugin that renders JSON examples so the initial render doesn't take up as much vertical space as the full JSON value serialized with newlines.\n For example, the plugin could collapse or minimize some values unless the end-user clicks to expand and show a fuller example that takes up more space.\n </p>\n </div>\n </section>\n </section>\n </section>\n </body>\n</html>\n"
The zcap-spec HTML, exactly as served at the time of the snapshot.
Annotated as
stringrather than left to inference, so the type is not the entire 81441-character literal.