@web3-storage/capabilities - npm Package Compare versions

Comparing version 2.1.0 to 2.2.0

dist/src/index.d.ts

@@ -1,3 +0,3 @@
-/** @type {import('./types').AbilitiesArray} */
-export const abilitiesAsStrings: import('./types').AbilitiesArray;
+/** @type {import('./types.js').AbilitiesArray} */
+export const abilitiesAsStrings: import('./types.js').AbilitiesArray;
 import * as Space from "./space.js";
@@ -4,0 +4,0 @@ import * as Top from "./top.js";

dist/src/types.d.ts

@@ -8,2 +8,6 @@ import type { TupleToUnion } from 'type-fest';
 import { claim, redeem } from './voucher.js';
+import * as AccessCaps from './access.js';
+export type Access = InferInvokedCapability<typeof AccessCaps.access>;
+export type AccessAuthorize = InferInvokedCapability<typeof AccessCaps.authorize>;
+export type AccessSession = InferInvokedCapability<typeof AccessCaps.session>;
 export type Space = InferInvokedCapability<typeof space>;
@@ -40,4 +44,7 @@ export type SpaceInfo = InferInvokedCapability<typeof info>;
     VoucherClaim['can'],
-    VoucherRedeem['can']
+    VoucherRedeem['can'],
+    Access['can'],
+    AccessAuthorize['can'],
+    AccessSession['can']
 ];
 //# sourceMappingURL=types.d.ts.map

dist/src/upload.d.ts

@@ -92,2 +92,53 @@ /**
 }, import("@ucanto/interface").CapabilityMatch<"*", import("@ucanto/interface").URI<"did:">, {}>>>>;
+export const all: import("@ucanto/interface").CapabilityParser<import("@ucanto/interface").DerivedMatch<{
+    can: "upload/add";
+    with: import("@ucanto/interface").URI<"did:">;
+    nb: import("@ucanto/interface").InferCaveats<{
+        /**
+         * Root CID of the DAG to be added to the upload list.
+         */
+        root: typeof Link;
+        /**
+         * CIDs to the CAR files that contain blocks of the DAG.
+         */
+        shards: Schema.Schema<import("@ucanto/interface").Link<unknown, 514, number, 1>[] | undefined, any>;
+    }>;
+}, import("@ucanto/interface").CapabilityMatch<"*", import("@ucanto/interface").URI<"did:">, {}> | import("@ucanto/interface").DerivedMatch<{
+    can: "upload/*";
+    with: import("@ucanto/interface").URI<"did:">;
+    nb?: import("@ucanto/interface").InferCaveats<{}> | undefined;
+}, import("@ucanto/interface").CapabilityMatch<"*", import("@ucanto/interface").URI<"did:">, {}>>> | import("@ucanto/interface").DerivedMatch<{
+    can: "upload/remove";
+    with: import("@ucanto/interface").URI<"did:">;
+    nb: import("@ucanto/interface").InferCaveats<{
+        /**
+         * Root CID of the DAG to be removed from the upload list.
+         */
+        root: typeof Link;
+    }>;
+}, import("@ucanto/interface").CapabilityMatch<"*", import("@ucanto/interface").URI<"did:">, {}> | import("@ucanto/interface").DerivedMatch<{
+    can: "upload/*";
+    with: import("@ucanto/interface").URI<"did:">;
+    nb?: import("@ucanto/interface").InferCaveats<{}> | undefined;
+}, import("@ucanto/interface").CapabilityMatch<"*", import("@ucanto/interface").URI<"did:">, {}>>> | import("@ucanto/interface").DerivedMatch<{
+    can: "upload/list";
+    with: import("@ucanto/interface").URI<"did:">;
+    nb: import("@ucanto/interface").InferCaveats<{
+        /**
+         * A pointer that can be moved back and forth on the list.
+         * It can be used to paginate a list for instance.
+         */
+        cursor: Schema.Schema<string | undefined, unknown>;
+        /**
+         * Maximum number of items per page.
+         */
+        size: Schema.Schema<(number & import("@ucanto/interface").Phantom<{
+            typeof: "integer";
+        }>) | undefined, unknown>;
+    }>;
+}, import("@ucanto/interface").CapabilityMatch<"*", import("@ucanto/interface").URI<"did:">, {}> | import("@ucanto/interface").DerivedMatch<{
+    can: "upload/*";
+    with: import("@ucanto/interface").URI<"did:">;
+    nb?: import("@ucanto/interface").InferCaveats<{}> | undefined;
+}, import("@ucanto/interface").CapabilityMatch<"*", import("@ucanto/interface").URI<"did:">, {}>>>>;
 import { Link } from "@ucanto/validator/src/schema.js";
@@ -94,0 +145,0 @@ import { Schema } from "@ucanto/validator/src/lib.js";

package.json

 {
   "name": "@web3-storage/capabilities",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Capabilities provided by web3.storage",
@@ -17,4 +17,4 @@ "homepage": "https://github.com/web3-storage/w3protocol/tree/main/packages/capabilities",
     ".": "./src/index.js",
-    "./types": "./dist/src/types.d.ts",
-    "./*": "./src/*.js"
+    "./*": "./src/*.js",
+    "./types": "./dist/src/types.d.ts"
   },
@@ -29,5 +29,2 @@ "typesVersions": {
       ],
-      "types": [
-        "dist/src/types"
-      ],
       "top": [
@@ -39,7 +36,13 @@ "dist/src/top"
       ],
+      "voucher": [
+        "dist/src/voucher"
+      ],
+      "access": [
+        "dist/src/access"
+      ],
       "utils": [
         "dist/src/utils"
       ],
-      "voucher": [
-        "dist/src/voucher"
+      "types": [
+        "dist/src/types"
       ]
@@ -54,7 +57,7 @@ }
   "dependencies": {
-    "@ucanto/core": "^4.0.2",
-    "@ucanto/interface": "^4.0.2",
-    "@ucanto/principal": "^4.0.2",
-    "@ucanto/transport": "^4.0.2",
-    "@ucanto/validator": "^4.0.2"
+    "@ucanto/core": "^4.2.3",
+    "@ucanto/interface": "^4.2.3",
+    "@ucanto/principal": "^4.2.3",
+    "@ucanto/transport": "^4.2.3",
+    "@ucanto/validator": "^4.2.3"
   },
@@ -64,5 +67,5 @@ "devDependencies": {
     "@types/mocha": "^10.0.0",
-    "@types/node": "^18.11.13",
+    "@types/node": "^18.11.18",
     "assert": "^2.0.0",
-    "hd-scripts": "^3.0.2",
+    "hd-scripts": "^4.0.0",
     "mocha": "^10.2.0",
@@ -69,0 +72,0 @@ "playwright-test": "^8.1.2",

readme.md

@@ -5,2 +5,10 @@ # ⁂ `@web3-storage/capabilities`
 
+## About
+
+The w3up platform by [web3.storage](https://web3.storage) is implemented as a set of capabilities that can be invoked using the [ucanto](https://github.com/web3-storage/ucanto) RPC framework.
+
+The `@web3-storage/capabilities` package contains capability definitions, which are used by clients to create invocations and by services to validate and parse invocations and route requests to the correct capability handler.
+
+See the [capabilities spec](https://github.com/web3-storage/w3protocol/tree/main/spec/capabilities.md) for more information about each capability included in this package.
+
 ## Install
@@ -29,1 +37,126 @@
 ```
+
+### Capability types
+
+The capability objects exported by this package are defined using ucanto's type-inference based capability parser. This results in concrete types that capture the details of each capability, allowing type-safe invocation and validation. 
+
+When inspecting the concrete types of a capability object (e.g. in your IDE), you may see something similar to the following:
+
+
+```ts
+const add: TheCapabilityParser<DerivedMatch<{
+    can: "store/add";
+    with: URI<"did:">;
+    nb: InferCaveats<{
+        link: typeof Store.Schema.Link;
+        size: Store.Schema.NumberSchema<number & Phantom<{
+            typeof: "integer";
+        }>, unknown>;
+        origin: Store.Schema.Schema<...>;
+    }>;
+}, CapabilityMatch<...> | DerivedMatch<...>>>
+```
+
+While this is a fairly complex type signature, most of the types exist to support the mechanics of the capability parser and can generally be ignored when using the capabilities. The most interesting part as a user is the definition in the `DerivedMatch` type constraint, which shows the inferred ability and the constraints upon the resource URI and the caveats. In the example above, the `can` field shows that this capability's ability is `"store/add"`, its resource URI (the `with` field) must have the `"did:"` scheme, and there are three caveats defined in the `nb` field: `link`, `size`, and `origin`, each of which have constraints on their allowed values.
+
+### Using the exported capabilities
+
+The capability object exposes three methods via the `TheCapabilityParser` interface: `create`, `invoke`, and `delegate`. 
+
+#### `create`
+
+The `create` method returns a "materialized" capability object, which is to say, a JS object containing the `can`, `with`, and `nb` fields needed to fully specify a UCAN capability.
+
+You must provide an input object containing a `with` resource URI that matches the constraints in the capability definition, as well as an `nb` object containing any caveats you want to include. If a capability has no caveats defined, or if all the caveats are optional, you may omit the `nb` field from the input.
+
+```ts
+const cap = Store.add.create({
+  with: 'did:key:z6MkwFPNubhwM66HNKeJYtBu1Rv9n1LZdJhbyhLFg97Qr6FG',
+  nb: {
+    link: 'bagbaieraspawtgooy5lptr7loyd3fxjsrgkamre3y6au3ga4df5bkhrxdkmq',
+    size: 20,
+  }
+})
+```
+
+The above would result in an object similar to the following:
+
+```js
+{
+  can: 'store/add',
+  with: 'did:key:z6MkwFPNubhwM66HNKeJYtBu1Rv9n1LZdJhbyhLFg97Qr6FG',
+  nb: {
+    link: 'bagbaieraspawtgooy5lptr7loyd3fxjsrgkamre3y6au3ga4df5bkhrxdkmq',
+    size: 20,
+  }
+}
+```
+
+#### `invoke`
+
+The `invoke` method returns an [invocation](https://github.com/ucan-wg/spec/#29-invocation) of the capability, which can be executed against a ucanto service.
+
+Like `create`, `invoke` accepts `with` and `nb` fields, and the inputs must match the constraints in the capability definition.
+
+Because invocations are a type of UCAN, you also need to supply some UCAN-related options. At minimum, you need to include the `issuer`, which is a `Signer` capable of signing a UCAN, and `audience`, which identifies the recipient by DID. You can also include any of the optional fields in the interface definition below:
+
+```ts
+interface UCANOptions {
+  audience: Principal
+  lifetimeInSeconds?: number
+  expiration?: UCAN.UTCUnixTimestamp
+  notBefore?: UCAN.UTCUnixTimestamp
+
+  nonce?: UCAN.Nonce
+
+  facts?: Fact[]
+  proofs?: Proof[]
+}
+```
+
+In the example below, we're generating a new `Signer` to act as the issuer of the invocation using the `@ucanto/principal/ed25519` package. Note that in a real application, the service would likely reject an invocation from this signer, as it does not have any delegated permissions. See the [access client package](https://github.com/web3-storage/w3protocol/tree/main/packages/access-client) for more about key management and delegation in practice.
+
+```ts
+import * as DID from '@ipld/dag-ucan/did'
+import * as ed25519 from '@ucanto/principal/ed25519'
+
+const issuer = await ed25519.generate()
+const audience = DID.parse('did:web:web3.storage')
+
+const invocation = Store.add.invoke({
+  issuer,
+  audience,
+  with: 'did:key:z6MkwFPNubhwM66HNKeJYtBu1Rv9n1LZdJhbyhLFg97Qr6FG',
+  nb: {
+    link: 'bagbaieraspawtgooy5lptr7loyd3fxjsrgkamre3y6au3ga4df5bkhrxdkmq',
+    size: 20,
+  }
+})
+```
+
+Note that creating an invocation does not automatically execute it. To send the invocation to a service, you need a ucanto `ConnectionView` configured to access the service, which you can pass into the `execute` method on the invocation object.
+
+```ts
+const result = await invocation.execute(serviceConnection)
+```
+
+#### `delegate`
+
+The `delegate` method allows you to create a ucanto `Delegation`, which allows another principal to invoke the capability.
+
+`delegate` accepts the same input as `invoke`, however the `nb` field is optional. If `nb` is present, the values provided will act as constraints on the invocations that can be made using the delegation. For example, creating a `store/add` delegation with the `size` caveat set to `1048576` would limit invocations made using the delegation to uploads of no more than 1MiB.
+
+```ts
+import * as DID from '@ipld/dag-ucan/did'
+import * as ed25519 from '@ucanto/principal/ed25519'
+
+const issuer = await ed25519.generate()
+const audience = DID.parse('did:web:web3.storage')
+
+const delegation = await Store.add.delegate({
+  issuer,
+  audience,
+  with: 'did:key:z6MkwFPNubhwM66HNKeJYtBu1Rv9n1LZdJhbyhLFg97Qr6FG',
+})
+```
+

src/index.js

@@ -6,2 +6,3 @@ import * as Space from './space.js'
 import * as Voucher from './voucher.js'
+import * as Access from './access.js'
 import * as Utils from './utils.js'
@@ -11,3 +12,3 @@
 
-/** @type {import('./types').AbilitiesArray} */
+/** @type {import('./types.js').AbilitiesArray} */
 export const abilitiesAsStrings = [
@@ -29,2 +30,5 @@ Top.top.can,
   Voucher.redeem.can,
+  Access.access.can,
+  Access.authorize.can,
+  Access.session.can,
 ]

src/types.ts

@@ -8,3 +8,11 @@ import type { TupleToUnion } from 'type-fest'
 import { claim, redeem } from './voucher.js'
+import * as AccessCaps from './access.js'
 
+// Access
+export type Access = InferInvokedCapability<typeof AccessCaps.access>
+export type AccessAuthorize = InferInvokedCapability<
+  typeof AccessCaps.authorize
+>
+export type AccessSession = InferInvokedCapability<typeof AccessCaps.session>
+
 // Space
@@ -51,3 +59,6 @@ export type Space = InferInvokedCapability<typeof space>
   VoucherClaim['can'],
-  VoucherRedeem['can']
+  VoucherRedeem['can'],
+  Access['can'],
+  AccessAuthorize['can'],
+  AccessSession['can']
 ]

src/upload.js

@@ -162,4 +162,6 @@ /**
 
+export const all = add.or(remove).or(list)
+
 // ⚠️ We export imports here so they are not omited in generated typedefs
 // @see https://github.com/microsoft/TypeScript/issues/51548
 export { Link, Schema }

src/utils.js

@@ -51,8 +51,8 @@ import { Failure } from '@ucanto/validator'
     return true
-  } else if (String(child) !== String(parent)) {
+  } else if (String(child) === String(parent)) {
+    return true
+  } else {
     return new Failure(
       `Constrain violation: ${child} violates imposed ${constraint} constraint ${parent}`
     )
-  } else {
-    return true
   }
@@ -77,3 +77,3 @@ }
     return new Failure(
-      `Link ${!claimed.nb.link ? '' : `${claimed.nb.link}`} violates imposed ${
+      `Link ${claimed.nb.link ? `${claimed.nb.link}` : ''} violates imposed ${
         delegated.nb.link
@@ -80,0 +80,0 @@ } constraint.`

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

74056

increased by26.12%

Number of package files

29

increased by11.54%

Lines of code

1546

increased by18.11%

Number of lines in readme file

161

increased by475%

Dependency changes

• Updated@ucanto/core@^4.2.3

• Updated@ucanto/interface@^4.2.3

• Updated@ucanto/principal@^4.2.3

• Updated@ucanto/transport@^4.2.3

• Updated@ucanto/validator@^4.2.3