# @pdsjs/npm

Host npm packages natively in an atproto account. Dist-tags, version
manifests and tarballs live in the account's PDS as a
`dev.pdsjs.npm.package` record plus blob storage, so a package rides along
in CAR backups, migrates with the account, and needs no separate registry
service:

```sh
npm config set registry https://pds.example.com/npm/
npm login
npm publish

npm install my-package   # anonymous
```

## How it works

- The registry serves under `/npm/` on the PDS hostname, because the npm
  protocol wants the URL root and the PDS owns it. Point npm at the
  registry per project with an `.npmrc`, or per scope with
  `@myscope:registry=`.
- One record per package (rkey = name with the leading `@` dropped and `/`
  replaced by `:`). It holds the dist-tags and, per version, blob
  references for the tarball and the version manifest, which keeps those
  blobs out of orphan cleanup. The packument is assembled from the
  manifest blobs with each tarball URL rewritten to the requesting origin.
- npm integrity is SHA-512, so the record carries the integrity strings;
  the server hashes each tarball at publish and refuses a body whose
  declared integrity disagrees.
- Publishing over an existing version is refused the way npm expects, and
  `npm dist-tag` works over the wire.

## Authentication

Installs are anonymous. Publishes authenticate with the account password
or an app password. `npm login` verifies through createSession and answers
the password back as the token, so the `_authToken` npm stores is the app
password itself and nothing server-side has to survive a restart. A
`.npmrc` written by hand works the same way:

```ini
registry=https://pds.example.com/npm/
//pds.example.com/npm/:_authToken=<app password>
```

## Enabling

Node:

```js
const server = await createServer({
  // ...
  experimental: { npm: true },
});
```

Cloudflare: set `PDS_EXPERIMENTAL_NPM = "true"`.

Both mount `createNpmExtension()` through core's `extensions` option. A
platform that builds `PersonalDataServer` itself does the same:

```js
import { createNpmExtension } from '@pdsjs/npm/extension';

new PersonalDataServer({
  // ...
  extensions: [createNpmExtension({ maxTarballSize: 32 * 1024 * 1024 })],
});
```

## Limits

- npm publishes the tarball base64-encoded inside one JSON body, buffered
  server-side; `maxTarballSize` bounds it (default 64 MB).
- Unpublish is not served; delete the `dev.pdsjs.npm.package` record
  instead and the orphan sweep frees the bytes.
- Search and the audit endpoints answer 404, which npm treats as the
  feature being absent.