Skip to content

Commit

Permalink
chore: small readme updates (#421)
Browse files Browse the repository at this point in the history 
This fixes the capability imports in the upload-client examples to close
#326

I didn't see any more references to the old import paths, but lmk if I
missed any.

I also changed the casing of `Agent` and `Space` in a few places; when I
first wrote the access client readme I went a little nuts with the
capitalization, but later decided it looked weird and stopped
capitalizing them everywhere. So this just makes things consistent with
the docs site, etc.
  • Loading branch information
@yusefnapora
yusefnapora authored Feb 7, 2023
1 parent a6cd4df commit 89c3e6c
Show file tree
Hide file tree
Showing 2 changed files with 26 additions and 27 deletions.
41 changes: 20 additions & 21 deletions packages/access-client/readme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,13 +3,13 @@

## About

The `@web3-storage/access` package provides an API for creating and managing "Agents," which are software entities that control private signing keys and can invoke capabilities on behalf of a user (or another Agent).
The `@web3-storage/access` package provides an API for creating and managing "agents," which are software entities that control private signing keys and can invoke capabilities on behalf of a user (or another agent).

Agents are used to invoke capabilities provided by the w3up service layer, using the [ucanto](https://github.com/web3-storage/ucanto) RPC framework. Agents are created locally on an end-user's device, and users are encouraged to create new Agents for each device (or browser) that they want to use, rather than sharing Agent keys between devices.
Agents are used to invoke capabilities provided by the w3up service layer, using the [ucanto](https://github.com/web3-storage/ucanto) RPC framework. Agents are created locally on an end-user's device, and users are encouraged to create new agents for each device (or browser) that they want to use, rather than sharing agent keys between devices.

An Agent can create "Spaces," which are namespaces for content stored on the w3up platform. Each Space has its own keypair, the public half of which is used to form a `did:key:` URI that uniquely identifies the Space. The Space's private key is used to delegate capabilities to a primary Agent, which then issues ucanto requests related to the Space.
An Agent can create "spaces," which are namespaces for content stored on the w3up platform. Each space has its own keypair, the public half of which is used to form a `did:key:` URI that uniquely identifies the space. The space's private key is used to delegate capabilities to a primary agent, which then issues ucanto requests related to the space.

Although Agents (and Spaces) are created locally by generating keypairs, the w3up services will only act upon Spaces that have been registered with the w3up access service. By default, a newly-created Agent will be configured to use the production access service for remote operations, including registration.
Although agents (and spaces) are created locally by generating keypairs, the w3up services will only act upon spaces that have been registered with the w3up access service. By default, a newly-created agent will be configured to use the production access service for remote operations, including registration.

Please note that the `@web3-storage/access` package is a fairly "low level" component of the w3up JavaScript stack, and most users will be better served by [`@web3-storage/w3up-client`](https://github.com/web3-storage/w3up-client), which combines this package with a client for the upload and storage service and presents a simpler API.

Expand All @@ -27,7 +27,7 @@ npm install @web3-storage/access

### Agent creation

To create an Agent, you must first create a `Store`, which the Agent will use to store and manage persistent state, including private keys.
To create an agent, you must first create a `Store`, which the agent will use to store and manage persistent state, including private keys.

If you're running in a web browser, use [`StoreIndexedDB`](https://web3-storage.github.io/w3protocol/classes/_web3_storage_access.StoreIndexedDB.html), which uses IndexedDB to store non-extractable [`CryptoKey`](https://www.w3.org/TR/WebCryptoAPI/#dfn-CryptoKey) objects. This prevents the private key material from ever being exposed to the JavaScript environment.

Expand Down Expand Up @@ -60,7 +60,7 @@ async function createAgent() {

On node.js, use [`StoreConf`](https://web3-storage.github.io/w3protocol/classes/_web3_storage_access.StoreConf.html), which uses the [`conf` package](https://www.npmjs.com/package/conf) to store keys and metadata in the user's platform-specific default configuration location (usually in their home directory).

Agents on node should use Ed25519 keys,
Agents on node should use Ed25519 keys:

```js
import { Agent } from '@web3-storage/access/agent'
Expand Down Expand Up @@ -91,15 +91,15 @@ async function createAgent() {

```

See the [`AgentCreateOptions` reference](https://web3-storage.github.io/w3protocol/interfaces/_web3_storage_access._internal_.AgentCreateOptions.html) if you want to configure the Agent to use a non-production service connection.
See the [`AgentCreateOptions` reference](https://web3-storage.github.io/w3protocol/interfaces/_web3_storage_access._internal_.AgentCreateOptions.html) if you want to configure the agent to use a non-production service connection.

### Space creation

A newly-created Agent does not have access to any Spaces, and is thus unable to store data using the w3up platform.
A newly-created agent does not have access to any spaces, and is thus unable to store data using the w3up platform.

To create a new Space, use [`agent.createSpace`](https://web3-storage.github.io/w3protocol/classes/_web3_storage_access.Agent.html#createSpace), optionally passing in a human-readable name.
To create a new space, use [`agent.createSpace`](https://web3-storage.github.io/w3protocol/classes/_web3_storage_access.Agent.html#createSpace), optionally passing in a human-readable name.

This will create a new signing keypair for the Space and use it to issue a non-expiring delegation for all Space-related capabilities to the Agent, which will persist the delegation in its Store for future use.
This will create a new signing keypair for the space and use it to issue a non-expiring delegation for all space-related capabilities to the agent, which will persist the delegation in its Store for future use.

The `createSpace` method returns an object describing the space:

Expand All @@ -124,23 +124,23 @@ interface CreateSpaceResult {

### Managing the current space

An Agent can create multiple Spaces and may also be issued delegations that allow it to manage Spaces created by other Agents. The Agent's `spaces` property is a `Map` keyed by Space DID, whose values are the metadata associated with each Space.
An agent can create multiple spaces and may also be issued delegations that allow it to manage spaces created by other agents. The agent's `spaces` property is a `Map` keyed by space DID, whose values are the metadata associated with each space.

Agents may also have a "current" space, which is used as the default Space for storage operations if none is specified. You can retrieve the DID of the current space with [`agent.currentSpace`](https://web3-storage.github.io/w3protocol/classes/_web3_storage_access.Agent.html#currentSpace). If you also want the metadata and proofs associated with the space, use [`agent.currentSpaceWithMeta`](https://web3-storage.github.io/w3protocol/classes/_web3_storage_access.Agent.html#currentSpaceWithMeta).
Agents may also have a "current" space, which is used as the default space for storage operations if none is specified. You can retrieve the DID of the current space with [`agent.currentSpace`](https://web3-storage.github.io/w3protocol/classes/_web3_storage_access.Agent.html#currentSpace). If you also want the metadata and proofs associated with the space, use [`agent.currentSpaceWithMeta`](https://web3-storage.github.io/w3protocol/classes/_web3_storage_access.Agent.html#currentSpaceWithMeta).

To set the current space, use [`agent.setCurrentSpace`](https://web3-storage.github.io/w3protocol/classes/_web3_storage_access.Agent.html#setCurrentSpace). Note that this must be done explicitly; creating an Agent's first Space does not automatically set it as the current space.
To set the current space, use [`agent.setCurrentSpace`](https://web3-storage.github.io/w3protocol/classes/_web3_storage_access.Agent.html#setCurrentSpace). Note that this must be done explicitly; creating an agent's first space does not automatically set it as the current space.

### Space registration

A newly-created Space must be registered with the w3up access service before it can be used as a storage location.
A newly-created space must be registered with the w3up access service before it can be used as a storage location.

To register a space, use [`agent.registerSpace`](https://web3-storage.github.io/w3protocol/classes/_web3_storage_access.Agent.html#registerSpace), which takes an email address parameter and registers the [current space](#managing-the-current-space) with the access service.

Calling `registerSpace` will cause the access service to send a confirmation email to the provided email address. When the activation link in the email is clicked, the service will send the Agent a delegation via a WebSocket connection that grants access to the services included in w3up's free tier. The `registerSpace` method returns a `Promise` that resolves once the registration process is complete. Make sure to wrap calls to `registerSpace` in a `try/catch` block, as registration will fail if the user does not confirm the email (or if network issues arise, etc.).
Calling `registerSpace` will cause the access service to send a confirmation email to the provided email address. When the activation link in the email is clicked, the service will send the agent a delegation via a WebSocket connection that grants access to the services included in w3up's free tier. The `registerSpace` method returns a `Promise` that resolves once the registration process is complete. Make sure to wrap calls to `registerSpace` in a `try/catch` block, as registration will fail if the user does not confirm the email (or if network issues arise, etc.).

### Delegating to another Agent
### Delegating to another agent

The Agent's [`delegate` method](https://web3-storage.github.io/w3protocol/classes/_web3_storage_access.Agent.html#delegate) allows you to delegate capabilities to another Agent.
The agent's [`delegate` method](https://web3-storage.github.io/w3protocol/classes/_web3_storage_access.Agent.html#delegate) allows you to delegate capabilities to another agent.

```js
const delegation = await agent.delegate({
Expand All @@ -156,12 +156,11 @@ const delegation = await agent.delegate({

Note that the receiving agent will need to [import the delegation](#importing-delegations-from-another-agent) before they will be able to invoke the delegated capabilities.

### Importing delegations from another Agent
### Importing delegations from another agent

The [`addProof` method](https://web3-storage.github.io/w3protocol/classes/_web3_storage_access.Agent.html#addProof) takes in a ucanto `Delegation` and adds it to the Agent's state Store. The proof of delegation can be retrieved using the Agent's [`proofs` method](https://web3-storage.github.io/w3protocol/classes/_web3_storage_access.Agent.html#proofs).
The [`addProof` method](https://web3-storage.github.io/w3protocol/classes/_web3_storage_access.Agent.html#addProof) takes in a ucanto `Delegation` and adds it to the agent's state Store. The proof of delegation can be retrieved using the agent's [`proofs` method](https://web3-storage.github.io/w3protocol/classes/_web3_storage_access.Agent.html#proofs).


The [`importSpaceFromDelegation` method](https://web3-storage.github.io/w3protocol/classes/_web3_storage_access.Agent.html#importSpaceFromDelegation) also accepts a ucanto `Delegation`, but it is tailored for "full delegation" of all Space-related capabilities. The delegated ability must be `*`, which is the "top" ability that can derive all abilities for the Space's DID. Use `importSpaceFromDelegation` in preference to `addProofs` when importing a full `*` delegation for a Space, as it also adds metadata about the imported Space to the Agent's persistent Store and adds the Space to the Agent's set of authorized spaces.
The [`importSpaceFromDelegation` method](https://web3-storage.github.io/w3protocol/classes/_web3_storage_access.Agent.html#importSpaceFromDelegation) also accepts a ucanto `Delegation`, but it is tailored for "full delegation" of all space-related capabilities. The delegated ability must be `*`, which is the "top" ability that can derive all abilities for the Space's DID. Use `importSpaceFromDelegation` in preference to `addProofs` when importing a full `*` delegation for a space, as it also adds metadata about the imported space to the Agent's persistent store and adds the space to the agent's set of authorized spaces.

## Contributing

Expand Down
12 changes: 6 additions & 6 deletions packages/upload-client/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,9 @@

The `@web3-storage/upload-client` package provides the "low level" client API for uploading data to [web3.storage](https://web3.storage) using the w3up platform.

Most users will be better served by the higher-level [`@web3-storage/w3up-client` package](https://github.com/web3-storage/w3up-client), which presents a simpler API and supports creating Agents and registering Spaces.
Most users will be better served by the higher-level [`@web3-storage/w3up-client` package](https://github.com/web3-storage/w3up-client), which presents a simpler API and supports creating agents and registering spaces.

If you are using this package directly instead of `w3up-client`, you will also need to use the [`@web3-storage/access` client](https://github.com/web3-storage/w3protocol/tree/main/packages/access-client) for Agent and Space management.
If you are using this package directly instead of `w3up-client`, you will also need to use the [`@web3-storage/access` client](https://github.com/web3-storage/w3protocol/tree/main/packages/access-client) for agent and space management. The `@web3-storage/capabilities` package referenced in the examples below is a transitive dependency of both `@web3-storage/upload-client` and `@web3-storage/access`, so you shouldn't need to install it explicitly.

## Install

Expand All @@ -21,18 +21,18 @@ npm install @web3-storage/upload-client

[API Reference](#api)

### Create an Agent
### Create an agent

An Agent provides:
An agent provides:

1. The key pair used to call the service and sign the payload (the `issuer`).
2. A decentralized identifier (DID) of the "space" where data should be uploaded (the `with`).
3. Proof showing your `issuer` has been delegated capabilities to store data and register uploads to the "space" (`proofs`).

```js
import { Agent } from '@web3-storage/access'
import { store } from '@web3-storage/access/capabilities/store'
import { upload } from '@web3-storage/access/capabilities/upload'
import { store } from '@web3-storage/capabilities/store'
import { upload } from '@web3-storage/capabilities/upload'

const agent = await Agent.create()

Expand Down

0 comments on commit 89c3e6c

Please sign in to comment.