Use wildcard capability

Author: Peeja

package-lock.json

@@ -55,6 +55,7 @@
     "@web3-storage/content-claims": "^5.0.0",
     "@web3-storage/public-bucket": "^1.1.0",
     "@web3-storage/upload-client": "^16.1.1",
+    "@web3-storage/w3cli": "^7.8.2",
     "carstream": "^2.1.0",
     "chai": "^5.1.1",
     "esbuild": "^0.18.20",

package.json

@@ -0,0 +1,4 @@
+declare module '@web3-storage/w3cli/lib.js' {
+  import { Client } from '@web3-storage/w3up-client'
+  export declare function getClient(): Promise<Client>
+}

scripts/delegate-serve.d.ts

@@ -1,33 +1,30 @@
 import sade from 'sade'
 import { getClient } from '@web3-storage/w3cli/lib.js'
-import { serve } from '../src/middleware/withAuthorizedSpace.js'
 import * as ed25519 from '@ucanto/principal/ed25519'
-
-/** @import { Client } from '@web3-storage/w3up-client' */
+import * as serve from '../src/capabilities/serve.js'
 
 const cli = sade('delegate-serve.js <space> [token]')
 
 cli
   .describe(
-    `Delegates ${serve.can} to the Gateway for <space>, with an optional token. Outputs a base64url string suitable for the stub_delegation query parameter. Pipe the output to pbcopy or similar for the quickest workflow.`
+    `Delegates ${serve.star.can} to the Gateway for <space>, with an optional token. Outputs a base64url string suitable for the stub_delegation query parameter. Pipe the output to pbcopy or similar for the quickest workflow.`
   )
   .action(async (space, token) => {
-    /** @type {Client} */
     const client = await getClient()
 
     const gatewayIdentity = (await ed25519.Signer.generate()).withDID(
       'did:web:w3s.link'
     )
 
-    const delegation = await serve.delegate({
+    const delegation = await serve.star.delegate({
       issuer: client.agent.issuer,
       audience: gatewayIdentity,
       with: space,
       nb: { token: token ?? null },
       expiration: Infinity,
       proofs: client.proofs([
         {
-          can: serve.can,
+          can: serve.star.can,
           with: space
         }
       ])

scripts/delegate-serve.js

@@ -0,0 +1,51 @@
+import { capability, Schema, DID, nullable, string } from '@ucanto/validator'
+
+/**
+ * "Manage the serving of content owned by the subject Space."
+ *
+ * A Principal who may `space/content/serve/*` is permitted to perform all
+ * operations related to serving content owned by the Space, including actually
+ * serving it and recording egress charges.
+ */
+export const star = capability({
+  can: 'space/content/serve/*',
+  /**
+   * The Space which contains the content. This Space will be charged egress
+   * fees if content is actually retrieved by way of this invocation.
+   */
+  with: DID,
+  nb: Schema.struct({
+    /** The authorization token, if any, used for this request. */
+    token: nullable(string())
+  })
+})
+
+/**
+ * "Serve content owned by the subject Space over HTTP."
+ *
+ * A Principal who may `space/content/serve/transport/http` is permitted to
+ * serve any content owned by the Space, in the manner of an [IPFS Gateway]. The
+ * content may be a Blob stored by a Storage Node, or indexed content stored
+ * within such Blobs (ie, Shards).
+ *
+ * Note that the args do not currently specify *what* content should be served.
+ * Invoking this command does not currently *serve* the content in any way, but
+ * merely validates the authority to do so. Currently, the entirety of a Space
+ * must use the same authorization, thus the content does not need to be
+ * identified. In the future, this command may refer directly to a piece of
+ * content by CID.
+ *
+ * [IPFS Gateway]: https://specs.ipfs.tech/http-gateways/path-gateway/
+ */
+export const transportHttp = capability({
+  can: 'space/content/serve/transport/http',
+  /**
+   * The Space which contains the content. This Space will be charged egress
+   * fees if content is actually retrieved by way of this invocation.
+   */
+  with: DID,
+  nb: Schema.struct({
+    /** The authorization token, if any, used for this request. */
+    token: nullable(string())
+  })
+})

src/capabilities/serve.js

@@ -1,15 +1,7 @@
 import { Verifier } from '@ucanto/principal'
-import {
-  capability,
-  Schema,
-  DID,
-  nullable,
-  string,
-  ok,
-  access,
-  Unauthorized
-} from '@ucanto/validator'
+import { ok, access, Unauthorized } from '@ucanto/validator'
 import { HttpError } from '@web3-storage/gateway-lib/util'
+import * as serve from '../capabilities/serve.js'
 
 /**
  * @import * as Ucanto from '@ucanto/interface'
@@ -20,36 +12,6 @@ import { HttpError } from '@web3-storage/gateway-lib/util'
  * @import { SpaceContext, DelegationsStorageContext } from './withAuthorizedSpace.types.js'
  */
 
-/**
- * "Serve content owned by the subject Space."
- *
- * A Principal who may `space/content/serve` is permitted to serve any
- * content owned by the Space, in the manner of an [IPFS Gateway]. The
- * content may be a Blob stored by a Storage Node, or indexed content stored
- * within such Blobs (ie, Shards).
- *
- * Note that the args do not currently specify *what* content should be
- * served. Invoking this command does not currently *serve* the content in
- * any way, but merely validates the authority to do so. Currently, the
- * entirety of a Space must use the same authorization, thus the content does
- * not need to be identified. In the future, this command may refer directly
- * to a piece of content by CID.
- *
- * [IPFS Gateway]: https://specs.ipfs.tech/http-gateways/path-gateway/
- */
-export const serve = capability({
-  can: 'space/content/serve',
-  /**
-   * The Space which contains the content. This Space will be charged egress
-   * fees if content is actually retrieved by way of this invocation.
-   */
-  with: DID,
-  nb: Schema.struct({
-    /** The authorization token, if any, used for this request. */
-    token: nullable(string())
-  })
-})
-
 /**
  * Attempts to locate the {@link IpfsUrlContext.dataCid}. If it's able to,
  * attempts to authorize the request to access the data.
@@ -134,14 +96,14 @@ const authorize = async (space, ctx) => {
   // Look up delegations that might authorize us to serve the content.
   const relevantDelegationsResult = await ctx.delegationsStorage.find({
     audience: ctx.gatewayIdentity.did(),
-    can: 'space/content/serve',
+    can: serve.transportHttp.can,
     with: space
   })
 
   if (relevantDelegationsResult.error) return relevantDelegationsResult
 
   // Create an invocation of the serve capability.
-  const invocation = await serve
+  const invocation = await serve.transportHttp
     .invoke({
       issuer: ctx.gatewayIdentity,
       audience: ctx.gatewayIdentity,
@@ -155,7 +117,7 @@ const authorize = async (space, ctx) => {
 
   // Validate the invocation.
   const accessResult = await access(invocation, {
-    capability: serve,
+    capability: serve.transportHttp,
     authority: ctx.gatewayIdentity,
     principal: Verifier,
     validateAuthorization: () => ok({})

src/middleware/withAuthorizedSpace.js

@@ -7,16 +7,14 @@ import { describe, it } from 'mocha'
 import { expect } from 'chai'
 import sinon from 'sinon'
 import * as ed25519 from '@ucanto/principal/ed25519'
-import {
-  serve,
-  withAuthorizedSpace
-} from '../../../src/middleware/withAuthorizedSpace.js'
+import { withAuthorizedSpace } from '../../../src/middleware/withAuthorizedSpace.js'
 import * as Digest from 'multiformats/hashes/digest'
 import { base64 } from 'multiformats/bases/base64'
 import { rejection } from './util/rejection.js'
 import { expectToBeInstanceOf } from './util/expectToBeInstanceOf.js'
 import { HttpError } from '@web3-storage/gateway-lib/util'
 import { createTestCID } from './util/createTestCID.js'
+import * as serve from '../../../src/capabilities/serve.js'
 
 /**
  * @import { MultihashDigest } from 'multiformats'
@@ -129,7 +127,7 @@ describe('withAuthorizedSpace', async () => {
           error: undefined
         }),
         delegationsStorage: createDelegationStorage([
-          await serve.delegate({
+          await serve.transportHttp.delegate({
             issuer: space,
             audience: gatewayIdentity,
             with: space.did(),
@@ -173,7 +171,7 @@ describe('withAuthorizedSpace', async () => {
           error: undefined
         }),
         delegationsStorage: createDelegationStorage([
-          await serve.delegate({
+          await serve.transportHttp.delegate({
             issuer: space,
             audience: gatewayIdentity,
             with: space.did(),
@@ -219,7 +217,7 @@ describe('withAuthorizedSpace', async () => {
             error: undefined
           }),
           delegationsStorage: createDelegationStorage([
-            await serve.delegate({
+            await serve.transportHttp.delegate({
               issuer: space,
               audience: gatewayIdentity,
               with: space.did(),
@@ -270,14 +268,14 @@ describe('withAuthorizedSpace', async () => {
         error: undefined
       }),
       delegationsStorage: createDelegationStorage([
-        await serve.delegate({
+        await serve.transportHttp.delegate({
           issuer: space1,
           audience: gatewayIdentity,
           with: space1.did(),
           nb: { token: 'space1-token' }
         }),
         // No authorization for space2
-        await serve.delegate({
+        await serve.transportHttp.delegate({
           issuer: space3,
           audience: gatewayIdentity,
           with: space3.did(),
@@ -395,7 +393,7 @@ describe('withAuthorizedSpace', async () => {
             }
           }),
           delegationsStorage: createDelegationStorage([
-            await serve.delegate({
+            await serve.transportHttp.delegate({
               issuer: space,
               audience: gatewayIdentity,
               with: space.did(),
@@ -439,7 +437,7 @@ describe('withAuthorizedSpace', async () => {
             }
           }),
           delegationsStorage: createDelegationStorage([
-            await serve.delegate({
+            await serve.transportHttp.delegate({
               issuer: space,
               audience: gatewayIdentity,
               with: space.did(),
@@ -482,7 +480,7 @@ describe('withAuthorizedSpace', async () => {
             }
           }),
           delegationsStorage: createDelegationStorage([
-            await serve.delegate({
+            await serve.transportHttp.delegate({
               issuer: space,
               audience: gatewayIdentity,
               with: space.did(),

test/unit/middleware/withAuthorizedSpace.spec.js

@@ -1,6 +1,5 @@
-
 {
-  "include": ["src", "test"],
+  "include": ["src", "test", "scripts"],
   "compilerOptions": {
     "declaration": true,
     "declarationMap": true,