feat: add access/delegate capability parser exported from @web3-storage/capabilities

packages/capabilities/package.json

@@ -89,7 +89,14 @@
       "unicorn/prefer-number-properties": "off",
       "unicorn/prefer-export-from": "off",
       "unicorn/no-array-reduce": "off",
-      "jsdoc/no-undefined-types": "error"
+      "jsdoc/no-undefined-types": [
+        "error",
+        {
+          "definedTypes": [
+            "Iterable"
+          ]
+        }
+      ]
     },
     "env": {
       "mocha": true

packages/capabilities/src/access.js

@@ -8,7 +8,7 @@
  *
  * @module
  */
-import { capability, URI, DID } from '@ucanto/validator'
+import { capability, URI, DID, Schema, Failure } from '@ucanto/validator'
 // @ts-ignore
 // eslint-disable-next-line no-unused-vars
 import * as Types from '@ucanto/interface'
@@ -108,3 +108,100 @@ export const claim = base.derive({
   }),
   derives: equalWith,
 })
+
+// https://github.com/web3-storage/specs/blob/main/w3-access.md#accessdelegate
+export const delegate = base.derive({
+  to: capability({
+    can: 'access/delegate',
+    /**
+     * Field MUST be a space DID with a storage provider. Delegation will be stored just like any other DAG stored using store/add capability.
+     *
+     * @see https://github.com/web3-storage/specs/blob/main/w3-access.md#delegate-with
+     */
+    with: DID.match({ method: 'key' }),
+    nb: {
+      // keys SHOULD be CIDs, but we won't require it in the schema
+      /**
+       * @type {Schema.Schema<AccessDelegateDelegations>}
+       */
+      delegations: Schema.dictionary({
+        value: Schema.Link.match(),
+      }),
+    },
+    derives: (claim, proof) => {
+      return (
+        fail(equalWith(claim, proof)) ||
+        fail(subsetsNbDelegations(claim, proof)) ||
+        true
+      )
+    },
+  }),
+  derives: (claim, proof) => {
+    // no need to check claim.nb.delegations is subset of proof
+    // because the proofs types here never include constraints on the nb.delegations set
+    return fail(equalWith(claim, proof)) || true
+  },
+})
+
+/**
+ * @typedef {Schema.Dictionary<string, Types.Link<unknown, number, number, 0 | 1>>} AccessDelegateDelegations
+ */
+
+/**
+ * Parsed Capability for access/delegate
+ *
+ * @typedef {object} ParsedAccessDelegate
+ * @property {string} can
+ * @property {object} nb
+ * @property {AccessDelegateDelegations} [nb.delegations]
+ */
+
+/**
+ * returns whether the claimed ucan is proves by the proof ucan.
+ * both are access/delegate, or at least have same semantics for `nb.delegations`, which is a set of delegations.
+ * checks that the claimed delegation set is equal to or less than the proven delegation set.
+ * usable with {import('@ucanto/interface').Derives}.
+ *
+ * @param {ParsedAccessDelegate} claim
+ * @param {ParsedAccessDelegate} proof
+ */
+function subsetsNbDelegations(claim, proof) {
+  const missingProofs = setDifference(
+    delegatedCids(claim),
+    new Set(delegatedCids(proof))
+  )
+  if (missingProofs.size > 0) {
+    return new Failure(
+      `unauthorized nb.delegations ${[...missingProofs].join(', ')}`
+    )
+  }
+  return true
+}
+
+/**
+ * iterate delegated UCAN CIDs from an access/delegate capability.nb.delegations value.
+ *
+ * @param {ParsedAccessDelegate} delegate
+ * @returns {Iterable<string>}
+ */
+function* delegatedCids(delegate) {
+  for (const d of Object.values(delegate.nb.delegations || {})) {
+    yield d.toString()
+  }
+}
+
+/**
+ * @template S
+ * @param {Iterable<S>} minuend - set to subtract from
+ * @param {Set<S>} subtrahend - subtracted from minuend
+ */
+function setDifference(minuend, subtrahend) {
+  /** @type {Set<S>} */
+  const difference = new Set()
+  for (const e of minuend) {
+    if (!subtrahend.has(e)) {
+      difference.add(e)
+    }
+  }
+  return difference
+}