tidy up package.json and READMEs ()

* identity: README example and tidy

* tidy up package metadata (package.json files)

* updated README headers/stubs for several packages

* crypto: longer README, with usage

* syntax: tweak README

* Apply suggestions from code review

Co-authored-by: Eric Bailey <git@esb.lol>
Co-authored-by: devin ivy <devinivy@gmail.com>

---------

Co-authored-by: Eric Bailey <git@esb.lol>
Co-authored-by: devin ivy <devinivy@gmail.com>
This commit is contained in:
bnewbold 2023-09-21 18:07:33 -07:00 committed by GitHub
parent 1487c9f1fe
commit 584dea52c4
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
27 changed files with 347 additions and 106 deletions

@ -1,6 +1,19 @@
{
"name": "@atproto/api",
"version": "0.6.15",
"license": "MIT",
"description": "Client library for atproto and Bluesky",
"keywords": [
"atproto",
"bluesky",
"api"
],
"homepage": "https://atproto.com",
"repository": {
"type": "git",
"url": "https://github.com/bluesky-social/atproto",
"directory": "packages/api"
},
"main": "src/index.ts",
"publishConfig": {
"main": "dist/index.js",
@ -16,12 +29,6 @@
"bench": "jest --config jest.bench.config.js",
"bench:profile": "node --inspect-brk ../../node_modules/.bin/jest --config jest.bench.config.js"
},
"license": "MIT",
"repository": {
"type": "git",
"url": "https://github.com/bluesky-social/atproto.git",
"directory": "packages/api"
},
"dependencies": {
"@atproto/common-web": "workspace:^",
"@atproto/lexicon": "workspace:^",

@ -1,17 +1,23 @@
{
"name": "@atproto/aws",
"version": "0.1.1",
"license": "MIT",
"description": "Shared AWS cloud API helpers for atproto services",
"keywords": [
"atproto",
"aws"
],
"homepage": "https://atproto.com",
"repository": {
"type": "git",
"url": "https://github.com/bluesky-social/atproto",
"directory": "packages/aws"
},
"main": "src/index.ts",
"publishConfig": {
"main": "dist/index.js",
"types": "dist/src/index.d.ts"
},
"license": "MIT",
"repository": {
"type": "git",
"url": "https://github.com/bluesky-social/atproto.git",
"directory": "packages/aws"
},
"scripts": {
"build": "node ./build.js",
"postbuild": "tsc --build tsconfig.build.json",

@ -1,3 +1,10 @@
# Bsky App View
# @atproto/bsky: Bluesky AppView Service
The Bsky App View. This contains the indexers and XRPC methods for reading data from the Bsky application.
TypeScript implementation of the `app.bsky` Lexicons backing the https://bsky.app microblogging application.
[![NPM](https://img.shields.io/npm/v/@atproto/bsky)](https://www.npmjs.com/package/@atproto/bsky)
[![Github CI Status](https://github.com/bluesky-social/atproto/actions/workflows/repo.yaml/badge.svg)](https://github.com/bluesky-social/atproto/actions/workflows/repo.yaml)
## License
MIT License

@ -2,9 +2,15 @@
"name": "@atproto/bsky",
"version": "0.0.6",
"license": "MIT",
"description": "Reference implementation of app.bsky App View (Bluesky API)",
"keywords": [
"atproto",
"bluesky"
],
"homepage": "https://atproto.com",
"repository": {
"type": "git",
"url": "https://github.com/bluesky-social/atproto.git",
"url": "https://github.com/bluesky-social/atproto",
"directory": "packages/bsky"
},
"main": "src/index.ts",

@ -1,3 +1,10 @@
# ATP Common Library for Web
# @atproto/common-web
A library containing code which is shared between web-friendly ATP packages.
Shared TypeScript code for other `@atproto/*` packages, which is web-friendly (runs in-browser).
[![NPM](https://img.shields.io/npm/v/@atproto/common)](https://www.npmjs.com/package/@atproto/common-web)
[![Github CI Status](https://github.com/bluesky-social/atproto/actions/workflows/repo.yaml/badge.svg)](https://github.com/bluesky-social/atproto/actions/workflows/repo.yaml)
## License
MIT License

@ -1,17 +1,22 @@
{
"name": "@atproto/common-web",
"version": "0.2.0",
"license": "MIT",
"description": "Shared web-platform-friendly code for atproto libraries",
"keywords": [
"atproto"
],
"homepage": "https://atproto.com",
"repository": {
"type": "git",
"url": "https://github.com/bluesky-social/atproto",
"directory": "packages/common-web"
},
"main": "src/index.ts",
"publishConfig": {
"main": "dist/index.js",
"types": "dist/index.d.ts"
},
"license": "MIT",
"repository": {
"type": "git",
"url": "https://github.com/bluesky-social/atproto.git",
"directory": "packages/common-web"
},
"scripts": {
"test": "jest",
"build": "node ./build.js",

@ -1,3 +1,10 @@
# ATP Common Library
# @atproto/common
A library containing code which is shared between ATP packages.
Shared TypeScript code for other `@atproto/*` packages. This package is oriented towards writing servers, and is not designed to be browser-compatible.
[![NPM](https://img.shields.io/npm/v/@atproto/common)](https://www.npmjs.com/package/@atproto/common)
[![Github CI Status](https://github.com/bluesky-social/atproto/actions/workflows/repo.yaml/badge.svg)](https://github.com/bluesky-social/atproto/actions/workflows/repo.yaml)
## License
MIT License

@ -1,17 +1,22 @@
{
"name": "@atproto/common",
"version": "0.3.0",
"license": "MIT",
"description": "Shared web-platform-friendly code for atproto libraries",
"keywords": [
"atproto"
],
"homepage": "https://atproto.com",
"repository": {
"type": "git",
"url": "https://github.com/bluesky-social/atproto",
"directory": "packages/common"
},
"main": "src/index.ts",
"publishConfig": {
"main": "dist/index.js",
"types": "dist/index.d.ts"
},
"license": "MIT",
"repository": {
"type": "git",
"url": "https://github.com/bluesky-social/atproto.git",
"directory": "packages/common"
},
"scripts": {
"test": "jest",
"build": "node ./build.js",

@ -1,3 +1,46 @@
# ATP Crypto Library
# @atproto/crypto
ATP's common cryptographic operations.
TypeScript library providing basic cryptographic helpers as needed in [atproto](https://atproto.com).
[![NPM](https://img.shields.io/npm/v/@atproto/crypto)](https://www.npmjs.com/package/@atproto/crypto)
[![Github CI Status](https://github.com/bluesky-social/atproto/actions/workflows/repo.yaml/badge.svg)](https://github.com/bluesky-social/atproto/actions/workflows/repo.yaml)
This package implements the two currently supported cryptographic systems:
- P-256 elliptic curve: aka "NIST P-256", aka secp256r1 (note the r), aka prime256v1
- K-256 elliptic curve: aka "NIST K-256", aka secp256k1 (note the k)
The details of cryptography in atproto are described in [the specification](https://atproto.com/specs/cryptography). This includes string encodings, validity of "low-S" signatures, byte representation "compression", hashing, and more.
## Usage
```typescript
import { verifySignature, Secp256k1Keypair, P256Keypair } from '@atproto/crypto'
// generate a new random K-256 private key
const keypair = await Secp256k1Keypair.create({ exportable: true })
// sign binary data, resulting signature bytes.
// SHA-256 hash of data is what actually gets signed.
// signature output is often base64-encoded.
const data = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8])
const sig = await keypair.sign(data)
// serialize the public key as a did:key string, which includes key type metadata
const pubDidKey = keypair.did()
console.log(pubDidKey)
// output would look something like: 'did:key:zQ3shVRtgqTRHC7Lj4DYScoDgReNpsDp3HBnuKBKt1FSXKQ38'
// verify signature using public key
const ok = verifySignature(pubDidKey, data, sig)
if (!ok) {
throw new Error('Uh oh, something is fishy')
} else {
console.log('Success')
}
```
## License
MIT License

@ -1,17 +1,23 @@
{
"name": "@atproto/crypto",
"version": "0.2.2",
"license": "MIT",
"description": "Library for cryptographic keys and signing in atproto",
"keywords": [
"atproto",
"cryptography"
],
"homepage": "https://atproto.com",
"repository": {
"type": "git",
"url": "https://github.com/bluesky-social/atproto",
"directory": "packages/crypto"
},
"main": "src/index.ts",
"publishConfig": {
"main": "dist/index.js",
"types": "dist/index.d.ts"
},
"license": "MIT",
"repository": {
"type": "git",
"url": "https://github.com/bluesky-social/atproto.git",
"directory": "packages/crypto"
},
"scripts": {
"test": "jest ",
"build": "node ./build.js",

@ -1,7 +1,10 @@
# ATP Developer Environment
# @atproto/dev-env: Local Developer Environment
A command-line application for developers to construct and manage development environments.
[![NPM](https://img.shields.io/npm/v/@atproto/dev-env)](https://www.npmjs.com/package/@atproto/dev-env)
[![Github CI Status](https://github.com/bluesky-social/atproto/actions/workflows/repo.yaml/badge.svg)](https://github.com/bluesky-social/atproto/actions/workflows/repo.yaml)
## REPL API
The following methods are available in the REPL.
@ -25,3 +28,7 @@ Create a new user.
### `user(handle: string): ServiceClient`
Get the `ServiceClient` for the given user.
## License
MIT License

@ -1,18 +1,23 @@
{
"name": "@atproto/dev-env",
"version": "0.2.6",
"license": "MIT",
"description": "Local development environment helper for atproto development",
"keywords": [
"atproto"
],
"homepage": "https://atproto.com",
"repository": {
"type": "git",
"url": "https://github.com/bluesky-social/atproto",
"directory": "packages/dev-env"
},
"main": "src/index.ts",
"publishConfig": {
"main": "dist/index.js",
"types": "dist/index.d.ts"
},
"bin": "dist/bin.js",
"license": "MIT",
"repository": {
"type": "git",
"url": "https://github.com/bluesky-social/atproto.git",
"directory": "packages/dev-env"
},
"scripts": {
"build": "node ./build.js",
"postbuild": "tsc --build tsconfig.build.json",

@ -1,3 +1,40 @@
# ATP DID Resolver
# @atproto/identity
A library for resolving ATP's Decentralized ID methods.
TypeScript library for decentralized identities in [atproto](https://atproto.com) using DIDs and handles
[![NPM](https://img.shields.io/npm/v/@atproto/identity)](https://www.npmjs.com/package/@atproto/identity)
[![Github CI Status](https://github.com/bluesky-social/atproto/actions/workflows/repo.yaml/badge.svg)](https://github.com/bluesky-social/atproto/actions/workflows/repo.yaml)
## Example
Resolving a Handle and verifying against DID document:
```typescript
const didres = new DidResolver({})
const hdlres = new HandleResolver({})
const handle = 'atproto.com'
const did = await hdlres.resolve(handle)
if (did == undefined) {
throw new Error('expected handle to resolve')
}
console.log(did) // did:plc:ewvi7nxzyoun6zhxrhs64oiz
const doc = await didres.resolve(did)
console.log(doc)
// additional resolutions of same DID will be cached for some time, unless forceRefresh flag is used
const doc2 = await didres.resolve(did, true)
// helper methods use the same cache
const data = await didres.resolveAtprotoData(did)
if (data.handle != handle) {
throw new Error('invalid handle (did not match DID document)')
}
```
## License
MIT License

@ -1,17 +1,24 @@
{
"name": "@atproto/identity",
"version": "0.2.0",
"license": "MIT",
"description": "Library for decentralized identities in atproto using DIDs and handles",
"keywords": [
"atproto",
"did",
"identity"
],
"homepage": "https://atproto.com",
"repository": {
"type": "git",
"url": "https://github.com/bluesky-social/atproto",
"directory": "packages/identity"
},
"main": "src/index.ts",
"publishConfig": {
"main": "dist/index.js",
"types": "dist/index.d.ts"
},
"license": "MIT",
"repository": {
"type": "git",
"url": "https://github.com/bluesky-social/atproto.git",
"directory": "packages/identity"
},
"scripts": {
"test": "jest",
"test:log": "cat test.log | pino-pretty",

@ -1,6 +1,18 @@
{
"name": "@atproto/lex-cli",
"version": "0.2.1",
"license": "MIT",
"description": "TypeScript codegen tool for atproto Lexicon schemas",
"keywords": [
"atproto",
"lexicon"
],
"homepage": "https://atproto.com",
"repository": {
"type": "git",
"url": "https://github.com/bluesky-social/atproto",
"directory": "packages/lex-cli"
},
"bin": {
"lex": "dist/index.js"
},
@ -14,12 +26,6 @@
"postbuild": "tsc --build tsconfig.build.json",
"update-main-to-dist": "node ../../update-main-to-dist.js packages/lex-cli"
},
"license": "MIT",
"repository": {
"type": "git",
"url": "https://github.com/bluesky-social/atproto.git",
"directory": "packages/lex-cli"
},
"dependencies": {
"@atproto/lexicon": "workspace:^",
"@atproto/syntax": "workspace:^",

@ -1,10 +1,9 @@
# Lexicon
# @atproto/lexicon: schema validation library
Lexicon is the semantic schemas & contracts system for ATP. This library provides definitions and APIs for ATP software.
TypeScript implementation of the Lexicon data and API schema description language, which is part of [atproto](https://atproto.com).
```
npm install @atproto/lexicon
```
[![NPM](https://img.shields.io/npm/v/@atproto/lexicon)](https://www.npmjs.com/package/@atproto/lexicon)
[![Github CI Status](https://github.com/bluesky-social/atproto/actions/workflows/repo.yaml/badge.svg)](https://github.com/bluesky-social/atproto/actions/workflows/repo.yaml)
## Usage
@ -29,3 +28,7 @@ lex.assertValidXrpcParams('com.example.query', {...})
lex.assertValidXrpcInput('com.example.procedure', {...})
lex.assertValidXrpcOutput('com.example.query', {...})
```
## License
MIT

@ -1,6 +1,18 @@
{
"name": "@atproto/lexicon",
"version": "0.2.1",
"license": "MIT",
"description": "atproto Lexicon schema language library",
"keywords": [
"atproto",
"lexicon"
],
"homepage": "https://atproto.com",
"repository": {
"type": "git",
"url": "https://github.com/bluesky-social/atproto",
"directory": "packages/lexicon"
},
"main": "src/index.ts",
"publishConfig": {
"main": "dist/index.js",
@ -12,12 +24,6 @@
"postbuild": "tsc --build tsconfig.build.json",
"update-main-to-dist": "node ../../update-main-to-dist.js packages/lexicon"
},
"license": "MIT",
"repository": {
"type": "git",
"url": "https://github.com/bluesky-social/atproto.git",
"directory": "packages/lexicon"
},
"dependencies": {
"@atproto/common-web": "workspace:^",
"@atproto/syntax": "workspace:^",

@ -1,3 +1,12 @@
# ATP Personal Data Server (PDS)
# @atproto/pds: Personal Data Server (PDS)
The Personal Data Server (PDS). This is ATP's main server-side implementation.
TypeScript reference implementation of an atproto PDS.
[![NPM](https://img.shields.io/npm/v/@atproto/pds)](https://www.npmjs.com/package/@atproto/pds)
[![Github CI Status](https://github.com/bluesky-social/atproto/actions/workflows/repo.yaml/badge.svg)](https://github.com/bluesky-social/atproto/actions/workflows/repo.yaml)
If you are interested in self-hosting a PDS, you probably want this repository instead, which has a thin service wrapper, documentation, a Dockerfile, etc: https://github.com/bluesky-social/pds
## License
MIT License

@ -2,9 +2,15 @@
"name": "@atproto/pds",
"version": "0.1.15",
"license": "MIT",
"description": "Reference implementation of atproto Personal Data Server (PDS)",
"keywords": [
"atproto",
"pds"
],
"homepage": "https://atproto.com",
"repository": {
"type": "git",
"url": "https://github.com/bluesky-social/atproto.git",
"url": "https://github.com/bluesky-social/atproto",
"directory": "packages/pds"
},
"main": "src/index.ts",

@ -1,3 +1,12 @@
# ATP Repo
# @atproto/repo: Repository and MST
The "ATP repository" core implementation (a Merkle Search Tree).
TypeScript library for atproto repositories, and in particular the Merkle Search Tree (MST) data structure.
[![NPM](https://img.shields.io/npm/v/@atproto/repo)](https://www.npmjs.com/package/@atproto/repo)
[![Github CI Status](https://github.com/bluesky-social/atproto/actions/workflows/repo.yaml/badge.svg)](https://github.com/bluesky-social/atproto/actions/workflows/repo.yaml)
Repositories in atproto are signed key/value stores containing CBOR-encoded data records. The structure and implementation details are described in [the specification](https://atproto.com/specs/repository). This includes MST node format, serialization, structural constraints, and more.
## License
MIT License

@ -1,17 +1,23 @@
{
"name": "@atproto/repo",
"version": "0.3.1",
"license": "MIT",
"description": "atproto repo and MST implementation",
"keywords": [
"atproto",
"mst"
],
"homepage": "https://atproto.com",
"repository": {
"type": "git",
"url": "https://github.com/bluesky-social/atproto",
"directory": "packages/repo"
},
"main": "src/index.ts",
"publishConfig": {
"main": "dist/index.js",
"types": "dist/index.d.ts"
},
"license": "MIT",
"repository": {
"type": "git",
"url": "https://github.com/bluesky-social/atproto.git",
"directory": "packages/repo"
},
"scripts": {
"test": "jest",
"test:profile": "node --inspect ../../node_modules/.bin/jest",

@ -1,9 +1,16 @@
# Syntax
# @atproto/syntax: validation helpers for identifier strings
Validation logic for AT identifiers - DIDs, Handles, NSIDs, and AT URIs.
Validation logic for [atproto](https://atproto.com) identifiers - DIDs, Handles, NSIDs, and AT URIs.
[![NPM](https://img.shields.io/npm/v/@atproto/crypto)](https://www.npmjs.com/package/@atproto/syntax)
[![Github CI Status](https://github.com/bluesky-social/atproto/actions/workflows/repo.yaml/badge.svg)](https://github.com/bluesky-social/atproto/actions/workflows/repo.yaml)
## Usage
### Handles
Syntax specification: <https://atproto.com/specs/handle>
```typescript
import { isValidHandle, ensureValidHandle, isValidDid } from '@atproto/syntax'
@ -17,7 +24,9 @@ ensureValidDid('did:method:val') // returns void
ensureValidDid(':did:method:val') // throws
```
## NameSpaced IDs (NSID)
### NameSpaced IDs (NSID)
Syntax specification: <https://atproto.com/specs/nsid>
```typescript
import { NSID } from '@atproto/syntax'
@ -43,7 +52,9 @@ NSID.isValid('example.com/foo') // => false
NSID.isValid('foo') // => false
```
## AT URI
### AT URI
Syntax specification: <https://atproto.com/specs/at-uri-scheme>
```typescript
import { AtUri } from '@atproto/syntax'

@ -1,6 +1,20 @@
{
"name": "@atproto/syntax",
"version": "0.1.1",
"license": "MIT",
"description": "Validation for atproto identifiers and formats: DID, handle, NSID, AT URI, etc",
"keywords": [
"atproto",
"did",
"nsid",
"at-uri"
],
"homepage": "https://atproto.com",
"repository": {
"type": "git",
"url": "https://github.com/bluesky-social/atproto",
"directory": "packages/syntax"
},
"main": "src/index.ts",
"publishConfig": {
"main": "dist/index.js",
@ -12,12 +26,6 @@
"postbuild": "tsc --build tsconfig.build.json",
"update-main-to-dist": "node ../../update-main-to-dist.js packages/syntax"
},
"license": "MIT",
"repository": {
"type": "git",
"url": "https://github.com/bluesky-social/atproto.git",
"directory": "packages/syntax"
},
"dependencies": {
"@atproto/common-web": "workspace:^"
},

@ -1,4 +1,9 @@
# XRPC Server API
# @atproto/xrpc-server: atproto HTTP API server library
TypeScript library for implementing [atproto](https://atproto.com) HTTP API services, with Lexicon schema validation.
[![NPM](https://img.shields.io/npm/v/@atproto/xrpc-server)](https://www.npmjs.com/package/@atproto/xrpc-server)
[![Github CI Status](https://github.com/bluesky-social/atproto/actions/workflows/repo.yaml/badge.svg)](https://github.com/bluesky-social/atproto/actions/workflows/repo.yaml)
## Usage

@ -1,6 +1,18 @@
{
"name": "@atproto/xrpc-server",
"version": "0.3.1",
"license": "MIT",
"description": "atproto HTTP API (XRPC) server library",
"keywords": [
"atproto",
"xrpc"
],
"homepage": "https://atproto.com",
"repository": {
"type": "git",
"url": "https://github.com/bluesky-social/atproto",
"directory": "packages/xrpc-server"
},
"main": "src/index.ts",
"publishConfig": {
"main": "dist/index.js",
@ -12,12 +24,6 @@
"postbuild": "tsc --build tsconfig.build.json",
"update-main-to-dist": "node ../../update-main-to-dist.js packages/xrpc-server"
},
"license": "MIT",
"repository": {
"type": "git",
"url": "https://github.com/bluesky-social/atproto.git",
"directory": "packages/xrpc-server"
},
"dependencies": {
"@atproto/common": "workspace:^",
"@atproto/crypto": "workspace:^",

@ -1,4 +1,9 @@
# XRPC API
# @atproto/xrpc: atproto HTTP API Client
TypeScript client library for talking to [atproto](https://atproto.com) services, with Lexicon schema validation.
[![NPM](https://img.shields.io/npm/v/@atproto/xrpc)](https://www.npmjs.com/package/@atproto/xrpc)
[![Github CI Status](https://github.com/bluesky-social/atproto/actions/workflows/repo.yaml/badge.svg)](https://github.com/bluesky-social/atproto/actions/workflows/repo.yaml)
## Usage

@ -1,6 +1,18 @@
{
"name": "@atproto/xrpc",
"version": "0.3.1",
"license": "MIT",
"description": "atproto HTTP API (XRPC) client library",
"keywords": [
"atproto",
"xrpc"
],
"homepage": "https://atproto.com",
"repository": {
"type": "git",
"url": "https://github.com/bluesky-social/atproto",
"directory": "packages/xrpc"
},
"main": "src/index.ts",
"publishConfig": {
"main": "dist/index.js",
@ -11,12 +23,6 @@
"postbuild": "tsc --build tsconfig.build.json",
"update-main-to-dist": "node ../../update-main-to-dist.js packages/xrpc"
},
"license": "MIT",
"repository": {
"type": "git",
"url": "https://github.com/bluesky-social/atproto.git",
"directory": "packages/xrpc"
},
"dependencies": {
"@atproto/lexicon": "workspace:^",
"zod": "^3.21.4"