feat: add store/get & upload/get capabilities (#82)

These capabilities are intended for checking inclusion, or getting the
additional properties we store. This will allow clients to verify all
the shards for an upload have been removed before removing an upload.

## `store/get` delegation

```js
{
  can: "store/get",
  with: "did:key:abc...",
  nb: {
    link: "bag...",
  }
}
```

### Response

Error if `link` shard cid is not in space or...

```ts
interface StoreListItem {
  /** CID of the stored CAR. */
  link: string

  /** Size in bytes of the stored CAR */
  size: number

  /** Link to a related CAR, used for sharded uploads */
  origin?: string,

  /** ISO-8601 timestamp when CAR was added to the space */
  insertedAt: string,
}
```

## `upload/get` delegation

```js
{
  can: "upload/get",
  with: "did:key:abc...",
  nb: {
    root: "bafyabc..."
  }
}
```

### Response

`Error` if root is not in uploads for space or...

```ts
interface UploadListItem {
  /** Root CID of the uploaded data item. */
  root: string

  /** CIDs of CARs that contain the complete DAG for the uploaded data item. */
  shards: string[]

  /** ISO-8601 timestamp when the upload was added to the space. */
  insertedAt: string,

  /** ISO-8601 timestamp when the upload entry was last modified. */
  updatedAt: string,
}
```

---

see also: storacha/w3up#942

License: MIT

---------

Signed-off-by: Oli Evans <[email protected]>

Author: olizilla

w3-store.md

@@ -22,11 +22,13 @@ The protocol is modeled as a set of capabilities which can be fulfilled by a [pr
   - [`store/` namespace](#store-namespace)
     - [`store/*`](#store)
     - [`store/add`](#storeadd)
+    - [`store/get`](#storeget)
     - [`store/remove`](#storeremove)
     - [`store/list`](#storelist)
   - [`upload/` namespace](#upload-namespace)
     - [`upload/*`](#upload)
     - [`upload/add`](#uploadadd)
+    - [`upload/get`](#uploadget)
     - [`upload/remove`](#uploadremove)
     - [`upload/list`](#uploadlist)
 
@@ -143,6 +145,66 @@ If `status == 'upload'`, the response will include additional fields containing
 
 The client should then make an HTTP `PUT` request to the `url` specified in the response, attaching all the included `headers`. The body of the request MUST be CAR data, whose size exactly equals the size specified in the `store/add` invocation's `size` caveat. Additionally, the CID of the uploaded CAR must match the invocation's `link` caveat. In other words, attempting to upload any data other than that authorized by the `store/add` invocation will fail.
 
+### `store/get`
+
+> Get metadata about a CAR shard from a space
+
+The `store/get` capability can be invoked to get metadata about a CAR from a [space](#spaces).
+
+This may be used to check for inclusion, or to get the `size` and `origin` properties for a shard.
+
+#### Derivations
+
+`store/get` can be derived from a [`store/*`](#store) or [`*`][ucan-spec-top] capability with a matching `with` field.
+
+#### Caveats
+
+When invoking `store/get`, the `link` caveat must be set to the CID of the CAR file to get metadata for.
+
+If a delegation contains a `link` caveat, an invocation derived from it must have the same CAR CID in its `link` field. A delegation without a `link` caveat may be invoked with any `link` value.
+
+| `field`   | `value`                           | `required?` | `context`                                     |
+| --------- | --------------------------------- | ----------- | --------------------------------------------- |
+| `link`    | CAR CID string, e.g. `bag...`     |             | The CID of the CAR to get metadata for        |
+
+#### Invocation
+
+```js
+{
+  can: "store/get",
+  with: "did:key:abc...",
+  nb: {
+    link: "bag...",
+  }
+}
+```
+
+#### Responses
+
+*Note*: This section is non-normative and subject to change, pending the [formalization of receipts and invocations][invocation-spec-pr].
+
+Executing a `store/get` invocation with a service provider should return a response object.
+
+If a failure occurs, the response will have an `error` field with a value of `true`, and a `message` string field with details about the error.
+
+On success, the response object will have the following shape:
+
+```ts
+interface StoreListItem {
+  /** CID of the stored CAR. */
+  link: string
+
+  /** Size in bytes of the stored CAR */
+  size: number
+
+  /** Link to a related CAR, used for sharded uploads */
+  origin?: string,
+
+  /** ISO-8601 timestamp when CAR was added to the space */
+  insertedAt: string,
+}
+```
+
 ### `store/remove`
 
 > Remove a stored CAR from a space
@@ -340,6 +402,68 @@ interface UploadAddResponse {
 }
 ```
 
+### `upload/get`
+
+> Get metadata about a upload from a space
+
+The `upload/get` capability can be invoked to get metadata about an upload from a [space](#spaces).
+
+This may be used to check for inclusion, or to get the set of CAR shards associated with a root CID.
+
+The `with` resource URI must be set to the DID of the space to get the upload metadata from.
+
+#### Derivations
+
+`upload/get` can be derived from an [`upload/*`](#upload) or [`*`][ucan-spec-top] capability with a matching `with` resource URI.
+
+#### Caveats
+
+The `root` caveat must contain the root CID of the item to get metadata for.
+
+| `field`   | `value`                           | `required?` | `context`                                                     |
+| --------- | --------------------------------- | ----------- | ------------------------------------------------------------- |
+| `root`    | data CID string, e.g. `bafy...`   |             | The root CID of the upload to get metadata for                |
+
+#### Invocation
+
+To invoke `upload/get`, an agent prepares a UCAN with the following shape:
+
+```js
+{
+  can: "upload/get",
+  with: "did:key:abc...",
+  nb: {
+    root: "bafyabc..."
+  }
+}
+```
+
+#### Responses
+
+*Note*: This section is non-normative and subject to change, pending the [formalization of receipts and invocations][invocation-spec-pr].
+
+Executing an `upload/get` invocation with a service provider should return a response object.
+
+If a failure occurs, the response will have an `error` field with a value of `true`, and a `message` string field with details about the error.
+
+On success, the response object will have the following shape:
+
+```ts
+interface UploadListItem {
+  /** Root CID of the uploaded data item. */
+  root: string
+
+  /** CIDs of CARs that contain the complete DAG for the uploaded data item. */
+  shards: string[]
+
+  /** ISO-8601 timestamp when the upload was added to the space. */
+  insertedAt: string,
+
+  /** ISO-8601 timestamp when the upload entry was last modified. */
+  updatedAt: string,
+}
+```
+
 ### `upload/remove`
 
 > Remove an upload from a space.