package-manager 0.0.1-preview.1
The Zena package manager's libraries: manifests, version selection, lockfiles, archives and the registry client
package-manager#
Client libraries for Zena packages published on AT Protocol: package manifests (zena-package.json), lockfiles (zena-lock.json), deterministic CAR source archives, dependency resolution, and registry queries. Versions and ranges are the package zena-lang:semver (packages/semver).
Usage#
import {readManifest} from 'package-manager/manifest';
import {Range} from 'zena-lang:semver';
let manifest = readManifest('{"name": "hello", "version": "1.0.0"}');
let version = manifest.version;
let matches = version != null && Range.parse('^1.0.0').includes(version);
Libraries#
package-manager/manifest: reading a package'szena-package.json, and rewriting its dependencies while keeping the rest of the file.package-manager/workspace: a workspace's packages, read from disk: the root's manifest, the packages it lists, and the ones they depend on by path.package-manager/files: which files a package publishes: its manifest'sfilespatterns, or by default every file but tests, and always the manifest, README, and license, never hidden files,node_modules, or the lockfile.package-manager/archive: source archives, the CAR files that hold a release's source. Packing is deterministic, so the same files always have the same CID, and unpacking accepts only what packing writes.package-manager/records: the profile, release, retraction, and maintainers records, an organization's members record, and the private membership entries it commits to, read from the atproto data model with the checks their lexicons describe, and written back. Also the rules for package names.package-manager/registry-methods: the NSIDs of the App View's XRPC methods.package-manager/registry: finding packages: resolving a DID, a handle, orscope:nameto a DID, a package's versions and retractions, its profile, and its releases with their proofs.package-manager/resolve: version selection, from the ranges in all of a workspace's manifests to what its lockfile pins, installing as few versions of each package as the ranges allow.package-manager/resolution: the packages a workspace's lockfile,zena-lock.json, pins, writing it, and what writing it changes in the pins already there (diffPins), including releases changed in place.package-manager/cache: the package cache, where each source archive is unpacked intosources/<CID>for the compiler to read.package-manager/fetch: fetching pinned packages into the cache. The release record's proof is checked against the account's signing key, the record and the source archive against the CIDs the lockfile pins, and the release's dependencies against the names it maps.package-manager/validate: checking a package directory and its manifest before publishing.package-manager/testing/fake-pds: an in-process PLC directory, DNS-over-HTTPS resolver, and PDS for package accounts, for testing code that finds and fetches packages.
22.5 KiB
Raw
/**
* A fake PLC directory, DNS-over-HTTPS resolver and PDS for package
* accounts, for testing what fetches and resolves packages. A `zena:http`
* server in the same program serves each account's DID document,
* `com.atproto.sync.getRecord`, `com.atproto.sync.getBlob`,
* `com.atproto.repo.getRecord` and `com.atproto.repo.listRecords`, and
* answers `_atproto` TXT queries for their handles. Each account's records
* are in a repository whose commit is signed with KEY, so every proof a
* client checks is a real one.
*
* ```zena
* let pds = new FakePds();
* pds.start();
* let source = pds.addBlob(packSource(files));
* let record = pds.publish(release);
* await fetchPackage(pin, cache, pds.resolver());
* pds.close();
* ```
*
* `FakePds`'s own methods act on the account DID; `account` adds others.
*
* An account with a `password` can also sign in with
* `com.atproto.server.createSession`, refresh and end the session, ask
* for service-auth tokens with `com.atproto.server.getServiceAuth`, which
* are signed with KEY like everything else, and write records to its own
* repository with `com.atproto.repo.putRecord`. Any account can sign in
* with OAuth too, at the fake's authorization server (`oauth`, from
* `fake-oauth`), and make the same two calls with its DPoP-bound tokens,
* as far as their scope allows.
*
* The PLC directory also takes operations, as `POST /plc/<did>`, which a
* package host sends for the accounts it creates elsewhere. It serves
* their DIDs' documents and answers for their handles.
*/
import {Future} from 'zena:async';
import {HashMap, OrderedHashMap} from 'zena:collections';
import {p256} from 'zena:crypto';
import {Borrow, Own, Unmanaged, parseI64} from 'zena:core';
import {hex} from 'zena:encoding';
import {App, Request, Response, Server} from 'zena:http';
import {JsonArray, JsonObject, parseJson, stringify} from 'zena:json';
import {now} from 'wasi:clocks/system-clock';
import {BlockMap, writeCar} from 'atproto/car';
import {encodeCbor} from 'atproto/cbor';
import {Cid} from 'atproto/cid';
import {BytesValue, IntValue, LinkValue, MapValue, NullValue, StringValue, fromJson, newMap, toJson} from 'atproto/data';
import {KeyType, formatMultikey, parseDidKey, publicKeyFor} from 'atproto/didkey';
import {IdentityResolver} from 'atproto/identity';
import {PlcOperation, didDocument as plcDidDocument, didOfGenesis} from 'atproto/plc';
import {fetch} from 'zena:fetch';
import {ServiceAuthClaims, createServiceAuthToken} from 'atproto/service-auth';
import {buildMst, compareKeys} from 'atproto/mst';
import {FakeAuthorizationServer, Grant, allowsRecords, allowsServiceAuth, refuseScope} from './fake-oauth.zena';
import {PROFILE_KEY, PROFILE_TYPE, Profile, RELEASE_TYPE, Release, RETRACTION_TYPE, Retraction} from '../records.zena';
import {
REPO_GET_RECORD, REPO_LIST_RECORDS, REPO_PUT_RECORD, SERVER_CREATE_SESSION, SERVER_DELETE_SESSION, SERVER_GET_SERVICE_AUTH,
SERVER_REFRESH_SESSION, SYNC_GET_BLOB, SYNC_GET_RECORD, xrpcPath
} from 'atproto/methods';
/** The first package account's DID. */
export let DID = 'did:plc:routerrouterrouterrouter';
/** The accounts' signing key: the P-256 key from RFC 6979, appendix A.2.5. */
export let KEY = hex.decode('c9afa9d845ba75166b5c215767b1d6934e50c3db36e89b127b8a622b120f6721');
/**
* The document of `did`, with its PDS at `origin`, the public key of
* `key`, and `handle` when it has one.
*/
export function didDocument(origin: String, key: FixedArray<u8> = KEY, did: String = DID,
handle: String | null = null): String {
let multikey = formatMultikey(publicKeyFor(KeyType.P256, key));
let aka = if (handle == null) '' else `"alsoKnownAs": ["at://${handle}"],`;
return `{
"id": "${did}",
${aka}
"verificationMethod": [
{"id": "${did}#atproto", "type": "Multikey", "controller": "${did}", "publicKeyMultibase": "${multikey}"}
],
"service": [
{"id": "#atproto_pds", "type": "AtprotoPersonalDataServer", "serviceEndpoint": "${origin}"}
]
}`;
}
/** One account on a FakePds: its document, records and blobs. */
export final class FakeAccount {
did: String;
handle: String | null;
/** The account's DID document, as JSON text. A test may replace it. */
var didDocument = '';
/** The account's records, by `<collection>/<rkey>`. */
records = new OrderedHashMap<String, MapValue>();
/** The account's blobs, by CID. */
blobs = new HashMap<String, FixedArray<u8>>();
/** The password `createSession` takes, or null when it refuses every one. */
var password: String | null = null;
new(did: String, handle: String | null) : did = did, handle = handle;
/** Stores `bytes` as a blob, and returns its CID. */
addBlob(bytes: FixedArray<u8>): Cid {
let cid = Cid.forBlob(bytes);
this.blobs[cid.toString()] = bytes;
return cid;
}
/** Adds `release` at its version, and returns the record's CID. */
publish(release: Release): Cid {
return this.put(RELEASE_TYPE, release.version.toString(), release.toValue());
}
/** Adds `retraction` at its version. */
retract(retraction: Retraction): void {
this.put(RETRACTION_TYPE, retraction.version.toString(), retraction.toValue());
}
/** Sets the account's profile. */
setProfile(profile: Profile): void {
this.put(PROFILE_TYPE, PROFILE_KEY, profile.toValue());
}
/** Stores `value` at `collection/rkey`, and returns its CID. */
put(collection: String, rkey: String, value: MapValue): Cid {
this.records[`${collection}/${rkey}`] = value;
return Cid.forDagCbor(encodeCbor(value));
}
/**
* The repository as a `getRecord` answer: every record, the tree over
* them and a commit signed with KEY.
*/
repositoryCar(): FixedArray<u8> {
let blocks = new BlockMap();
let keys = new GrowableArray<String>();
for (let key in this.records.keys()) {
keys.push(key);
}
let sorted = sortByBytes(keys);
let values = new FixedArray<Cid>(sorted.length, Cid.forBlob(new FixedArray<u8>(0, 0 as u8)));
for (var i = 0; i < sorted.length; i += 1) {
values[i] = blocks.add(this.records[sorted[i]]);
}
let root = buildMst(sorted, values, blocks);
let commit = newMap();
commit.entries['did'] = new StringValue(this.did);
commit.entries['version'] = new IntValue(3 as i64);
commit.entries['data'] = new LinkValue(root);
commit.entries['rev'] = new StringValue('3l3qo2vutsw2b');
commit.entries['prev'] = new NullValue();
commit.entries['sig'] = new BytesValue(p256.sign(KEY, encodeCbor(commit)));
return writeCar(new FixedArray<Cid>(1, blocks.add(commit)), blocks);
}
/** A `listRecords` answer for `collection`, every record on one page. */
listRecordsJson(collection: String): String {
let records = new JsonArray();
let prefix = `${collection}/`;
this.records.forEach((key, value) => {
if (key.startsWith(prefix)) {
records.push(this.#recordJson(key, value));
}
});
let page = new JsonObject();
page['records'] = records;
return stringify(page);
}
/**
* A `com.atproto.repo.getRecord` answer for `collection/rkey`, or null
* when there is no such record.
*/
getRecordJson(collection: String, rkey: String): String | null {
let key = `${collection}/${rkey}`;
if (let (true, value) = this.records.get(key)) {
return stringify(this.#recordJson(key, value));
}
return null;
}
/** The record at `key`, as `getRecord` and `listRecords` give it. */
#recordJson(key: String, value: MapValue): JsonObject {
let entry = new JsonObject();
entry['uri'] = `at://${this.did}/${key}`;
entry['cid'] = Cid.forDagCbor(encodeCbor(value)).toString();
entry['value'] = toJson(value);
return entry;
}
}
/** A fake PLC directory, DNS resolver and PDS. */
export final class FakePds {
/** The accounts, by DID. */
accounts = new OrderedHashMap<String, FakeAccount>();
/** How many requests the server has answered. */
var requests = 0;
/** The server's origin, `http://127.0.0.1:<port>`, once it has started. */
var origin = '';
/**
* The live sessions' tokens: each access token and refresh token
* mapped to its account's DID.
*/
accessTokens = new HashMap<String, String>();
refreshTokens = new HashMap<String, String>();
var #sessions = 0;
/** The latest operation the PLC directory took for each DID it was sent. */
operations = new OrderedHashMap<String, PlcOperation>();
/**
* A PLC directory to read the DIDs the fake does not hold from, such as
* `https://plc.directory`, so that real accounts resolve too; none when
* null, as in tests, which reach no network.
*/
var upstreamPlc: String | null = null;
/** The `(aud, lxm)` of each service-auth token handed out, in order. */
serviceAuthRequests = new GrowableArray<(String, String)>();
/** The authorization server, which signs in with OAuth. */
oauth = new FakeAuthorizationServer();
/** Kept open: the fake runs until `close`, past the owner's scope. */
var #server: Unmanaged<Server> | null = null;
new() {
this.accounts[DID] = new FakeAccount(DID, null);
}
/** A new session for `account`, as `createSession` answers with it. */
newSession(account: FakeAccount): String {
this.#sessions += 1;
let access = `access-${this.#sessions}`;
let refresh = `refresh-${this.#sessions}`;
this.accessTokens[access] = account.did;
this.refreshTokens[refresh] = account.did;
let session = new JsonObject();
session['did'] = account.did;
session['handle'] = account.handle ?? 'handle.invalid';
session['accessJwt'] = access;
session['refreshJwt'] = refresh;
return stringify(session);
}
/** Starts serving, on `port`, or one of the system's choosing for 0. */
start(port: i32 = 0): void {
let server = serve(this, port).keepOpen();
this.#server = server;
this.origin = `http://127.0.0.1:${server.port as i32}`;
this.accounts.forEach((did, account) => {
account.didDocument = didDocument(this.origin, KEY, did, account.handle);
});
}
/**
* Adds an account, with `handle` if given, and returns it. Call after
* `start`, so that its document names the server.
*/
account(did: String, handle: String | null = null): FakeAccount {
let account = new FakeAccount(did, handle);
account.didDocument = didDocument(this.origin, KEY, did, handle);
this.accounts[did] = account;
return account;
}
/** The account DID. */
main: FakeAccount {
get {
return this.accounts[DID];
}
}
/** DID's document, as JSON text. A test may replace it. */
didDocument: String {
get {
return this.main.didDocument;
}
set(value) {
this.main.didDocument = value;
}
}
/** DID's blobs, by CID. */
blobs: HashMap<String, FixedArray<u8>> {
get {
return this.main.blobs;
}
}
/** The PLC directory's origin, for `IdentityResolver.plcDirectory`. */
plcDirectory: String {
get {
return `${this.origin}/plc`;
}
}
/** The DNS-over-HTTPS endpoint, for `IdentityResolver.dnsOverHttps`. */
dnsOverHttps: String {
get {
return `${this.origin}/dns-query`;
}
}
/** A resolver that finds the accounts' documents and handles here. */
resolver(): IdentityResolver {
let resolver = new IdentityResolver();
resolver.plcDirectory = this.plcDirectory;
resolver.dnsOverHttps = this.dnsOverHttps;
let origin = this.origin;
resolver.originOf = (host) => origin;
return resolver;
}
/** Stores `bytes` as a blob of DID, and returns its CID. */
addBlob(bytes: FixedArray<u8>): Cid {
return this.main.addBlob(bytes);
}
/** Adds `release` to DID's repository, and returns the record's CID. */
publish(release: Release): Cid {
return this.main.publish(release);
}
/** Completes when the server stops. */
done(): Future<void> {
let server = this.#server;
if (server == null) {
throw new Error('the fake PDS was not started');
}
return server.done;
}
close(): void {
let server = this.#server;
if (server != null) {
server.close();
}
}
}
function serve(pds: FakePds, port: i32): Own<Server> {
let app = new App();
app.use(async (req, res, next): Future<void> => {
pds.requests += 1;
let path = req.path;
let params = req.url.searchParams();
if (path.startsWith('/plc/')) {
let did = path.sliceBytes(5, path.length);
if (req.method == 'POST') {
let operation = PlcOperation.fromJson(parseJson(await req.text()));
let refusal = plcRefusal(pds, did, operation);
if (refusal != null) {
res.statusCode = 400;
res.type = 'application/json';
res.body = stringify(errorJson(refusal));
return;
}
pds.operations[did] = operation;
res.body = '';
return;
}
if (let (true, account) = pds.accounts.get(did)) {
res.type = 'application/json';
res.body = account.didDocument;
} else if (let (true, operation) = pds.operations.get(did)) {
res.type = 'application/json';
res.body = stringify(plcDidDocument(did, operation));
} else if (pds.upstreamPlc != null) {
// A DID the fake does not hold, such as a real account's, from the
// directory it reads through to.
let answer = await fetch(`${pds.upstreamPlc as String}/${did}`);
res.statusCode = answer.status;
res.type = 'application/json';
res.body = await answer.text();
} else {
res.statusCode = 404;
res.body = 'no such DID';
}
return;
}
if (path == '/dns-query') {
res.type = 'application/dns-json';
let name = params.get('name') ?? '';
var did: String | null = null;
pds.accounts.forEach((accountDid, account) => {
if (account.handle != null && name == `_atproto.${account.handle as String}`) {
did = accountDid;
}
});
pds.operations.forEach((operationDid, operation) => {
for (let aka in operation.alsoKnownAs) {
if (name == `_atproto.${aka.sliceBytes(5, aka.length)}`) {
did = operationDid;
}
}
});
let found = did;
res.body = if (found == null) {
'{"Status":3}'
} else {
`{"Status":0,"Answer":[{"name":"${name}.","type":16,"data":${stringify(`"did=${found}"`)}}]}`
};
return;
}
if (path.startsWith('/.well-known/oauth-') || path.startsWith('/oauth/')) {
await pds.oauth.serve(req, res, pds.origin, (hint) => accountNamed(pds, hint));
return;
}
if (path.startsWith('/xrpc/com.atproto.server.')) {
await serveSession(pds, req, res);
return;
}
if (path == xrpcPath(REPO_PUT_RECORD)) {
await servePutRecord(pds, req, res);
return;
}
let did = params.get('did') ?? params.get('repo') ?? '';
if (let (true, account) = pds.accounts.get(did)) {
if (path == xrpcPath(SYNC_GET_RECORD)) {
res.type = 'application/vnd.ipld.car';
res.body = account.repositoryCar();
return;
}
if (path == xrpcPath(SYNC_GET_BLOB)) {
let cid = params.get('cid') ?? '';
if (let (true, blob) = account.blobs.get(cid)) {
res.type = 'application/octet-stream';
res.body = blob;
return;
}
res.statusCode = 400;
res.type = 'application/json';
res.body = '{"error":"BlobNotFound","message":"no such blob"}';
return;
}
if (path == xrpcPath(REPO_LIST_RECORDS)) {
res.type = 'application/json';
res.body = account.listRecordsJson(params.get('collection') ?? '');
return;
}
if (path == xrpcPath(REPO_GET_RECORD)) {
res.type = 'application/json';
let found = account.getRecordJson(params.get('collection') ?? '', params.get('rkey') ?? '');
if (found != null) {
res.body = found;
return;
}
res.statusCode = 400;
res.body = '{"error":"RecordNotFound","message":"no such record"}';
return;
}
}
res.statusCode = 400;
res.type = 'application/json';
res.body = '{"error":"InvalidRequest","message":"no such method or repository"}';
});
let server = new Server(app, port as u16);
server.start();
return server;
}
/** Why the directory refuses `operation` for `did`, or null when it takes it. */
function plcRefusal(pds: FakePds, did: String, operation: PlcOperation): String | null {
if (operation.prev == null) {
try {
if (didOfGenesis(operation) != did) {
return `the genesis operation makes another DID than ${did}`;
}
} catch (e) {
return e.message;
}
return null;
}
if (let (true, previous) = pds.operations.get(did)) {
if (previous.cid().toString() != operation.prev as String) {
return 'prev is not the latest operation';
}
for (let key in previous.rotationKeys) {
if (operation.isSignedBy(parseDidKey(key))) {
return null;
}
}
return 'no rotation key of the previous operation signed it';
}
return `${did} has no operation to follow`;
}
function errorJson(message: String): JsonObject {
let json = new JsonObject();
json['message'] = message;
return json;
}
/** The DID document the operation `operation` gives `did`. */
/** The DID of the account a login hint, a DID or a handle, names, or null. */
function accountNamed(pds: FakePds, hint: String): String | null {
var found: String | null = null;
pds.accounts.forEach((did, account) => {
if (did == hint || (account.handle != null && account.handle as String == hint)) {
found = did;
}
});
return found;
}
/**
* The account a request is signed in as: by a password session's bearer
* token, or by an OAuth access token and its proof, which `oauth` checks.
* Null when it is neither, after an OAuth refusal answers itself.
*/
function signedInAs(pds: FakePds, req: Borrow<Request>, res: Response): String | Grant | null {
let authorization = req.getHeader('authorization') ?? '';
if (authorization.startsWith('DPoP ')) {
return pds.oauth.checkAccess(req, res, `${pds.origin}${req.path}`);
}
let token = if (authorization.startsWith('Bearer ')) authorization.sliceBytes(7, authorization.length) else '';
if (let (true, did) = pds.accessTokens.get(token)) {
return did;
}
return null;
}
/** `com.atproto.repo.putRecord`, for a signed-in account's own repository. */
async function servePutRecord(pds: FakePds, req: Own<Request>, res: Response): Future<void> {
let oauth = (req.getHeader('authorization') ?? '').startsWith('DPoP ');
let caller = signedInAs(pds, req, res);
if (caller == null && oauth) {
// checkAccess answered the refusal.
return;
}
let input = parseJson(await req.text()) as JsonObject;
res.type = 'application/json';
if (caller is Grant && !allowsRecords(caller.scope, input['collection'] as String)) {
refuseScope(res);
return;
}
let signedIn: String | null = if (caller is Grant) caller.did else if (caller is String) caller else null;
if (signedIn != null) {
let did = signedIn;
if (input['repo'] as String != did) {
res.statusCode = 403;
res.body = '{"error":"Forbidden","message":"not your repository"}';
return;
}
let collection = input['collection'] as String;
let rkey = input['rkey'] as String;
let cid = pds.accounts[did].put(collection, rkey, fromJson(input['record']) as MapValue);
let answer = new JsonObject();
answer['uri'] = `at://${did}/${collection}/${rkey}`;
answer['cid'] = cid.toString();
res.body = stringify(answer);
return;
}
res.statusCode = 401;
res.body = '{"error":"AuthenticationRequired","message":"sign in first"}';
}
/** Answers the session methods of `com.atproto.server`. */
async function serveSession(pds: FakePds, req: Own<Request>, res: Response): Future<void> {
let path = req.path;
let bearer = req.getHeader('authorization') ?? '';
let token = if (bearer.startsWith('Bearer ')) bearer.sliceBytes(7, bearer.length) else '';
res.type = 'application/json';
let fail = (status: i32, error: String) => {
res.statusCode = status;
res.body = `{"error":"${error}","message":"${error}"}`;
};
if (path == xrpcPath(SERVER_CREATE_SESSION)) {
let input = parseJson(await req.text()) as JsonObject;
let identifier = input['identifier'] as String;
var found: FakeAccount | null = null;
pds.accounts.forEach((did, account) => {
if (did == identifier || (account.handle != null && account.handle as String == identifier)) {
found = account;
}
});
let account = found;
if (account == null || account.password == null ||
account.password as String != input['password'] as String) {
fail(401, 'AuthenticationRequired');
return;
}
res.body = pds.newSession(account);
return;
}
if (path == xrpcPath(SERVER_REFRESH_SESSION)) {
if (let (true, did) = pds.refreshTokens.get(token)) {
pds.refreshTokens.delete(token);
res.body = pds.newSession(pds.accounts[did]);
return;
}
fail(400, 'ExpiredToken');
return;
}
if (path == xrpcPath(SERVER_DELETE_SESSION)) {
pds.refreshTokens.delete(token);
res.body = '{}';
return;
}
if (path == xrpcPath(SERVER_GET_SERVICE_AUTH)) {
let params = req.url.searchParams();
let aud = params.get('aud') ?? '';
let lxm = params.get('lxm') ?? '';
let caller = signedInAs(pds, req, res);
if (caller is Grant && !allowsServiceAuth(caller.scope, lxm)) {
refuseScope(res);
return;
}
let signedIn: String | null = if (caller is Grant) caller.did else if (caller is String) caller else null;
if (signedIn != null) {
let did = signedIn;
let seconds = now().seconds;
var expires = seconds + 60;
if (let (true, exp) = parseI64(params.get('exp') ?? '')) {
expires = exp;
}
pds.serviceAuthRequests.push((aud, lxm));
let claims = new ServiceAuthClaims(did, aud, expires, seconds, lxm,
`nonce-${pds.serviceAuthRequests.length}`);
let body = new JsonObject();
body['token'] = createServiceAuthToken(claims, KeyType.P256, KEY);
res.body = stringify(body);
return;
}
if (!bearer.startsWith('DPoP ')) {
fail(400, 'ExpiredToken');
}
return;
}
fail(400, 'InvalidRequest');
}
/** `keys` sorted byte by byte, as the tree wants them. */
function sortByBytes(keys: GrowableArray<String>): FixedArray<String> {
let sorted = new FixedArray<String>(keys.length, '');
for (var i = 0; i < keys.length; i += 1) {
// Insertion sort: test repositories hold a handful of records.
var j = i;
while (j > 0 && compareKeys(sorted[j - 1], keys[i]) > 0) {
sorted[j] = sorted[j - 1];
j -= 1;
}
sorted[j] = keys[i];
}
return sorted;
}
- atproto atproto.zena-lang.pkg.zena-lang.dev ~0.0.1-preview.1
- zena-lang:semver semver.zena-lang.pkg.zena-lang.dev ~0.0.1-preview.1
| Version | Published | Dependencies | Approved by |
|---|---|---|---|
| 0.0.1-preview.1 | 2026-11-19 |
|
|