Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fix: repo URLs #1550

Merged
merged 4 commits into from
Sep 16, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 8 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# `w3up`

This repo implements the web3.storage UCAN protocol [specifications](https://github.com/web3-storage/specs).
This repo implements the web3.storage UCAN protocol [specifications](https://github.com/storacha/specs).

It's the core of the web3.storage server and client implementations.

Expand All @@ -18,7 +18,7 @@ Once uploaded you can fetch your data from any IPFS gateway via [`https://w3s.li

### Command Line

Install [`@web3-storage/w3cli`](https://github.com/web3-storage/w3cli#readme) globally, authorize it to act on your behalf, create a space and upload your files. It calculates the root CID for your files locally before sending them to web3.storage.
Install [`@web3-storage/w3cli`](https://github.com/storacha/w3cli#readme) globally, authorize it to act on your behalf, create a space and upload your files. It calculates the root CID for your files locally before sending them to web3.storage.

**shell**
```shell
Expand All @@ -34,11 +34,11 @@ $ w3 up ~/Pictures/ayy-lamo.jpg
⁂ https://w3s.link/ipfs/bafybeid6gpbsqkpfrsx6b6ywrt24je4xqe4eo4y2wldisl6sk7byny5uky
```

Run `w3 --help` or have a look at https://github.com/web3-storage/w3cli to find out everything it can do.
Run `w3 --help` or have a look at https://github.com/storacha/w3cli to find out everything it can do.

### JS Client

Add the [`@web3-storage/w3up-client`](https://www.npmjs.com/package/@web3-storage/w3up-client) module into your project with `npm i @web3-storage/w3up-client` and upload a single file with [`client.uploadFile`](https://github.com/web3-storage/w3up/blob/main/packages/w3up-client/README.md#uploadfile) or many with [`client.uploadDirectory`](https://github.com/web3-storage/w3up/blob/main/packages/w3up-client/README.md#uploaddirectory).
Add the [`@web3-storage/w3up-client`](https://www.npmjs.com/package/@web3-storage/w3up-client) module into your project with `npm i @web3-storage/w3up-client` and upload a single file with [`client.uploadFile`](https://github.com/storacha/w3up/blob/main/packages/w3up-client/README.md#uploadfile) or many with [`client.uploadDirectory`](https://github.com/storacha/w3up/blob/main/packages/w3up-client/README.md#uploaddirectory).

If you've already got a space you can upload like this:

Expand All @@ -63,11 +63,11 @@ console.log(`Gateway URL: https://w3s.link/ipfs/${cid}`)

See https://web3.storage/docs/w3up-client for a guide to using the js client for the first time.

For an interactive command line adventure into the using w3up check out `learnyouw3up` here https://github.com/web3-storage/learnyouw3up
For an interactive command line adventure into the using w3up check out `learnyouw3up` here https://github.com/storacha/learnyouw3up

### GitHub Action

The Action [`add-to-web3`](https://github.com/marketplace/actions/add-to-web3) wraps [`w3cli`](https://github.com/web3-storage/w3cli) to let you add files to web3.storage from your GitHub Workflows.
The Action [`add-to-web3`](https://github.com/marketplace/actions/add-to-web3) wraps [`w3cli`](https://github.com/storacha/w3cli) to let you add files to web3.storage from your GitHub Workflows.

**github-workflow.yaml**
```yaml
Expand All @@ -86,13 +86,13 @@ The Action [`add-to-web3`](https://github.com/marketplace/actions/add-to-web3) w
# "https://dweb.link/ipfs/bafkreicysg23kiwv34eg2d7qweipxwosdo2py4ldv42nbauguluen5v6am"
```

To generate a `secret_key` and delegate permissions to it as a `proof` to use in CI see: https://github.com/web3-storage/add-to-web3#generating-a-secret_key-and-proof
To generate a `secret_key` and delegate permissions to it as a `proof` to use in CI see: https://github.com/storacha/add-to-web3#generating-a-secret_key-and-proof

## Contributing

All welcome! web3.storage is open-source. See the [contributing guide](./CONTRIBUTING.md)

This project uses node v18 and `pnpm`. It's a monorepo that uses [pnpm workspaces](https://pnpm.io/workspaces) to handle resolving dependencies between the local [`packages`](https://github.com/web3-storage/w3up/tree/main/packages)
This project uses node v18 and `pnpm`. It's a monorepo that uses [pnpm workspaces](https://pnpm.io/workspaces) to handle resolving dependencies between the local [`packages`](https://github.com/storacha/w3up/tree/main/packages)

## License

Expand Down
2 changes: 1 addition & 1 deletion packages/access-client/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
"homepage": "https://web3.storage",
"repository": {
"type": "git",
"url": "https://github.com/w3s-project/w3up.git",
"url": "https://github.com/storacha/w3up.git",
"directory": "packages/access-client"
},
"author": "Hugo Dias <[email protected]> (hugodias.me)",
Expand Down
30 changes: 15 additions & 15 deletions packages/access-client/readme.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,13 +5,13 @@

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/storacha/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.

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.
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/storacha/w3up-client), which combines this package with a client for the upload and storage service and presents a simpler API.

## Install

Expand All @@ -23,13 +23,13 @@ npm install @web3-storage/access

## Usage

[API Reference](https://web3-storage.github.io/w3protocol/modules/_web3_storage_access.html)
[API Reference](https://web3-storage.github.io/w3up/modules/_web3_storage_access.html)

### 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.

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.
If you're running in a web browser, use [`StoreIndexedDB`](https://web3-storage.github.io/w3up/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.

Agents in a browser use RSA keys, which can be generated using the async `generate` function from `@ucanto/principal/rsa`.

Expand Down Expand Up @@ -58,7 +58,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).
On node.js, use [`StoreConf`](https://web3-storage.github.io/w3up/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).
alanshaw marked this conversation as resolved.
Show resolved Hide resolved

Agents on node should use Ed25519 keys:

Expand Down Expand Up @@ -91,13 +91,13 @@ 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/w3up/interfaces/_web3_storage_access._internal_.AgentCreateOptions.html) if you want to configure the agent to use a non-production service connection.
alanshaw marked this conversation as resolved.
Show resolved Hide resolved

### Space creation

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/w3up/classes/_web3_storage_access.Agent.html#createSpace), optionally passing in a human-readable name.
alanshaw marked this conversation as resolved.
Show resolved Hide resolved

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.

Expand Down Expand Up @@ -126,21 +126,21 @@ interface CreateSpaceResult {

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/w3up/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/w3up/classes/_web3_storage_access.Agent.html#currentSpaceWithMeta).
alanshaw marked this conversation as resolved.
Show resolved Hide resolved

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/w3up/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.
alanshaw marked this conversation as resolved.
Show resolved Hide resolved

### Space registration

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.
To register a space, use [`agent.registerSpace`](https://web3-storage.github.io/w3up/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.
alanshaw marked this conversation as resolved.
Show resolved Hide resolved

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

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/w3up/classes/_web3_storage_access.Agent.html#delegate) allows you to delegate capabilities to another agent.
alanshaw marked this conversation as resolved.
Show resolved Hide resolved

```js
const delegation = await agent.delegate({
Expand All @@ -158,15 +158,15 @@ Note that the receiving agent will need to [import the delegation](#importing-de

### 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/w3up/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/w3up/classes/_web3_storage_access.Agent.html#proofs).
alanshaw marked this conversation as resolved.
Show resolved Hide resolved

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/w3up/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.
alanshaw marked this conversation as resolved.
Show resolved Hide resolved

## Contributing

Feel free to join in. All welcome. Please [open an issue](https://github.com/web3-storage/w3protocol/issues)!
Feel free to join in. All welcome. Please [open an issue](https://github.com/storacha/w3up/issues)!

## License

Dual-licensed under [MIT + Apache 2.0](https://github.com/web3-storage/w3protocol/blob/main/license.md)
Dual-licensed under [MIT + Apache 2.0](https://github.com/storacha/w3up/blob/main/license.md)

2 changes: 1 addition & 1 deletion packages/access-client/src/agent.js
Original file line number Diff line number Diff line change
Expand Up @@ -239,7 +239,7 @@ export class Agent {
}
}
const receipt = await this.invokeAndExecute(UCAN.revoke, {
// per https://github.com/web3-storage/w3up/blob/main/packages/capabilities/src/ucan.js#L38C6-L38C6 the resource here should be
// per https://github.com/storacha/w3up/blob/main/packages/capabilities/src/ucan.js#L38C6-L38C6 the resource here should be
// the current issuer - using the space DID here works for simple cases but falls apart when a delegee tries to revoke a delegation
// they have re-delegated, since they don't have "ucan/revoke" capabilities on the space
with: this.issuer.did(),
Expand Down
4 changes: 2 additions & 2 deletions packages/blob-index/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,8 +55,8 @@ for (const [shard, slices] of index.shards.entries()) {

## Contributing

Feel free to join in. All welcome. Please [open an issue](https://github.com/web3-storage/w3up/issues)!
Feel free to join in. All welcome. Please [open an issue](https://github.com/storacha/w3up/issues)!

## License

Dual-licensed under [MIT + Apache 2.0](https://github.com/web3-storage/w3up/blob/main/license.md)
Dual-licensed under [MIT + Apache 2.0](https://github.com/storacha/w3up/blob/main/license.md)
2 changes: 1 addition & 1 deletion packages/blob-index/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
"homepage": "https://web3.storage",
"repository": {
"type": "git",
"url": "https://github.com/w3s-project/w3up.git",
"url": "https://github.com/storacha/w3up.git",
"directory": "packages/blob-index"
},
"license": "Apache-2.0 OR MIT",
Expand Down
2 changes: 1 addition & 1 deletion packages/blob-index/src/api.ts
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ export type Position = [offset: number, length: number]
/**
* A sharded DAG index.
*
* @see https://github.com/w3s-project/specs/blob/main/w3-index.md
* @see https://github.com/storacha/specs/blob/main/w3-index.md
*/
export interface ShardedDAGIndex {
/** DAG root CID that the index pertains to. */
Expand Down
2 changes: 1 addition & 1 deletion packages/capabilities/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
"homepage": "https://web3.storage",
"repository": {
"type": "git",
"url": "https://github.com/w3s-project/w3up.git",
"url": "https://github.com/storacha/w3up.git",
"directory": "packages/capabilities"
},
"license": "(Apache-2.0 OR MIT)",
Expand Down
Loading
Loading