@wovin/core 0.1.35 → 0.2.0

package/src/ipfs/ipfs-utils.ts

@@ -0,0 +1,132 @@
+import * as dagJson from '@ipld/dag-json'
+import { sha256 } from '@noble/hashes/sha2.js'
+import { Logger } from 'besonders-logger'
+import { CID, digest as Digest } from 'multiformats'
+import { encode as multiformatsEncode } from 'multiformats/block'
+// import { encode } from 'multiformats/block';
+import { Applog, ApplogEncNoCid, ApplogNoCid, ApplogOfSomeSort, CidString, IpnsString, isEncryptedApplog } from '../applog/datom-types.ts'
+
+import { base36 } from 'multiformats/bases/base36'
+import { sha256 as sha265Hasher } from 'multiformats/hashes/sha2'
+
+/* THIS FILE SHOULD NOT DEPEND ON UI STUFF, SO THAT TESTS CAN RUN WITH MINIMAL DEPENDENCIES */
+
+const { WARN, LOG, DEBUG, VERBOSE, ERROR } = Logger.setup(Logger.INFO) // eslint-disable-line no-unused-vars
+
+export const MULTICODEC_IPNS_KEY = 0x72
+
+export function prepareForPub(log: ApplogOfSomeSort, without: string[] = ['cid']) {
+	if (!log) throw ERROR('falsy log', log)
+	let cid = (log as Applog).cid
+	if (isEncryptedApplog(log)) {
+		if (!cid) cid = getCidSync(encodeBlock(log as ApplogEncNoCid).bytes).toString()
+		WARN('preparing an encrypted applog - really?')
+		return { log, cid }
+	}
+	const logWithout = {}
+	for (let [key, val] of Object.entries(log)) {
+		if (val === undefined) {
+			WARN(`log.${key} is undefined, which is not allowed - encoding as null`, log)
+			val = null
+		}
+		if (!without.includes(key)) {
+			logWithout[key] = val // && key === 'pv' ? CID.parse(val) : val //HACK: disabled until clarified: https://discuss.ipfs.tech/t/pin-dag-with-open-ends/17612
+		} else {
+			VERBOSE('excluding app log', { key, val })
+		}
+	}
+	return { log: logWithout as Applog, cid }
+}
+
+export function encodeApplogAndGetCid(log: ApplogNoCid) {
+	return getCidSync(encodeApplog(log).bytes)
+}
+export function encodeApplog(log: ApplogNoCid | ApplogEncNoCid): { bytes: dagJson.ByteView<any>; cid: CID } {
+	return encodeBlock(prepareForPub(log)?.log)
+}
+
+export function getCidSync(bytes: dagJson.ByteView<any>) {
+	// Hacky way to use a sync sha265 lib to create a CID - code inspired by https://github.com/multiformats/js-multiformats#multihash-hashers
+	const hash = sha256(bytes)
+	const digest = Digest.create(sha265Hasher.code, hash)
+	const cid = CID.create(1, dagJson.code, digest)
+	VERBOSE(`[getCidSync]`, { bytes, hash, digest, cid })
+	return cid
+}
+/** encode the json object into an IPLD block */
+export function encodeBlock(jsonObject: any): { bytes: dagJson.ByteView<any>; cid: CID } {
+	DEBUG('[encodeBlock]', jsonObject)
+	try {
+		const byteView = dagJson.encode(jsonObject)
+		return { bytes: byteView, cid: getCidSync(byteView) }
+	} catch (err) {
+		throw ERROR('[encodeBlock] failed to encode:', jsonObject, err)
+	}
+}
+
+export async function encodeBlockOriginal(jsonObject: any) {
+	// HACK re-added this to verify the sync variant is sane
+	const encoded = await multiformatsEncode({ value: jsonObject, codec: dagJson, hasher: sha265Hasher })
+	const syncVariant = encodeBlock(jsonObject)
+	if (syncVariant.cid.toString() !== encoded.cid.toString()) {
+		ERROR(`[encodeBlockOriginal] sync cid mismatch`, { jsonObject, encoded, syncVariant })
+	}
+	return encoded
+}
+
+export function tryParseCID(cidString: CidString) {
+	let cid: CID | null = null
+	let errors = []
+	try {
+		cid = CID.parse(cidString)
+	} catch (err) {
+		VERBOSE(`[retrieveThread] couldn't parse pubID with default base`)
+		errors.push(err)
+	}
+	if (!cid) {
+		try {
+			cid = CID.parse(cidString, base36) // e.g. for IPNS
+		} catch (err) {
+			VERBOSE(`[retrieveThread] couldn't parse pubID with base36`)
+			errors.push(err)
+		}
+	}
+	return {
+		cid,
+		errors: cid ? null : errors, // we only care about errors if we failed to parse
+		isIpns: cid && isIpnsKeyCid(cid),
+	}
+}
+export function isIpnsKeyCid(cid: CID) {
+	return cid.code === MULTICODEC_IPNS_KEY
+}
+
+export function cidToString(cid: CID) {
+	if (cid.code == MULTICODEC_IPNS_KEY) {
+		return toIpnsString(cid)
+	} else {
+		return cid.toString()
+	}
+}
+export function toIpnsString(cid: CID) {
+	if (cid.code !== MULTICODEC_IPNS_KEY) throw ERROR(`Not an IPNS cid (${cid.code}):`, cid.toString())
+	return cid.toString(base36) as IpnsString
+}
+export function ensureValidCIDinstance(cidOrStringA: CID | CidString) {
+	return typeof cidOrStringA === 'string'
+		? CID.parse(cidOrStringA)
+		: typeof cidOrStringA.toV1 != 'function'
+		? CID.decode(cidOrStringA.bytes)
+		: cidOrStringA
+}
+export function areCidsEqual(cidOrStringA: CID | CidString, cidOrStringB: CID | CidString) {
+	if (!cidOrStringA || !cidOrStringB) throw new Error(`[areCidsEqual] invalid params: ${cidOrStringA}, ${cidOrStringB}`)
+	if (cidOrStringA === cidOrStringB) return true // shortcut if both are strings
+	const cidA = ensureValidCIDinstance(cidOrStringA)
+	const cidB = ensureValidCIDinstance(cidOrStringB)
+	return cidA.toV1().toString() === cidB.toV1().toString()
+}
+export function containsCid(list: (CID | CidString)[] | Set<CidString>, needle: CID | CidString) {
+	if (list instanceof Set) return list.has(typeof needle === 'string' ? needle : needle.toV1().toString()) // ? what if the CidString is a different form? (parse and format would cost performance)
+	return list.some(cidOrString => areCidsEqual(cidOrString, needle))
+}

package/src/ipfs.ts

@@ -0,0 +1,3 @@
+export * from './ipfs/car.ts'
+export * from './ipfs/ipfs-utils.ts'
+export * from './ipfs/fetch-snapshot-chain.ts'

package/src/ipns/ipns-record.ts

@@ -0,0 +1,115 @@
+import { createIPNSRecord, marshalIPNSRecord, unmarshalIPNSRecord } from 'ipns'
+import { privateKeyFromRaw } from '@libp2p/crypto/keys'
+import { base36 } from 'multiformats/bases/base36'
+import { base64pad } from 'multiformats/bases/base64'
+import type { CID } from 'multiformats/cid'
+
+export interface SignedIPNSRecord {
+	recordBytes: Uint8Array   // marshalled protobuf, signed — the wire format
+	ipnsName: string          // k51... string
+	value: string             // /ipfs/<cid>
+	sequence: bigint
+}
+
+/** Derive IPNS name string (k51...) from Ed25519 private key bytes */
+export function ipnsNameFromPrivateKey(privKeyBytes: Uint8Array): string {
+	const privKey = privateKeyFromRaw(privKeyBytes)
+	return privKey.publicKey.toCID().toString(base36)
+}
+
+/**
+ * Create a signed IPNS record (protobuf wire format).
+ * Same bytes can be published to any naming service.
+ */
+export async function createSignedIPNSRecord(
+	privateKey: Uint8Array,
+	cid: CID,
+	sequence: bigint,
+	lifetimeMs = 365 * 24 * 60 * 60 * 1000, // 1 year
+): Promise<SignedIPNSRecord> {
+	const privKey = privateKeyFromRaw(privateKey)
+	const value = `/ipfs/${cid.toV1()}`
+	const record = await createIPNSRecord(privKey, value, sequence, lifetimeMs)
+	const recordBytes = marshalIPNSRecord(record)
+	const ipnsName = privKey.publicKey.toCID().toString(base36)
+	return { recordBytes, ipnsName, value, sequence }
+}
+
+export { unmarshalIPNSRecord }
+
+/** A target that can receive a signed IPNS record */
+export interface IPNSPublishTarget {
+	name: string
+	publish(ipnsName: string, recordBytes: Uint8Array): Promise<void>
+}
+
+/**
+ * Resolve current IPNS sequence number from a naming service.
+ * Returns null if the name was never published (404).
+ * Throws on network/server errors.
+ */
+export async function resolveIPNSSequence(
+	nameServiceUrl: string,
+	ipnsName: string,
+): Promise<bigint | null> {
+	const url = `${nameServiceUrl}/name/${ipnsName}`
+	let response: Response
+	try {
+		response = await fetch(url)
+	} catch (err) {
+		throw new Error(`Network error resolving IPNS ${ipnsName}: ${err}`)
+	}
+
+	if (response.status === 404) return null
+	if (!response.ok) {
+		throw new Error(`HTTP ${response.status} resolving IPNS ${ipnsName}: ${response.statusText}`)
+	}
+
+	const { record, value } = await response.json()
+	if (!record && !value) return null // never published
+
+	// If raw record is available, unmarshal to get sequence
+	if (record) {
+		const bytes = base64pad.baseDecode(record)
+		const entry = unmarshalIPNSRecord(bytes)
+		return entry.sequence
+	}
+
+	// Some servers return value but not raw record — can't get sequence
+	return 0n
+}
+
+/**
+ * Create a signed IPNS record and publish to all configured targets.
+ * Resolves sequence from sequenceServiceUrl, creates record once, fans out.
+ * Throws if ALL targets fail; warns on partial failure.
+ */
+export async function publishIPNSRecord(
+	privateKey: Uint8Array,
+	cid: CID,
+	targets: IPNSPublishTarget[],
+	sequenceServiceUrl = 'https://name.web3.storage',
+): Promise<SignedIPNSRecord> {
+	const ipnsName = ipnsNameFromPrivateKey(privateKey)
+	const currentSeq = await resolveIPNSSequence(sequenceServiceUrl, ipnsName)
+	const sequence = currentSeq != null ? currentSeq + 1n : 0n
+	const signed = await createSignedIPNSRecord(privateKey, cid, sequence)
+
+	const results = await Promise.allSettled(
+		targets.map(t => t.publish(ipnsName, signed.recordBytes))
+	)
+	const failures = results
+		.map((r, i) => ({ r, name: targets[i].name }))
+		.filter(({ r }) => r.status === 'rejected') as { r: PromiseRejectedResult; name: string }[]
+
+	if (failures.length > 0 && failures.length < targets.length) {
+		// Partial failure — log but don't throw
+		for (const { r, name } of failures) {
+			console.warn(`[publishIPNSRecord] target '${name}' failed:`, r.reason)
+		}
+	} else if (failures.length === targets.length) {
+		throw new Error(`All IPNS publish targets failed: ${failures.map(({ r, name }) => `${name}: ${r.reason}`).join('; ')}`)
+	}
+
+	return signed
+}

package/src/ipns.ts

@@ -0,0 +1 @@
+export * from './ipns/ipns-record.ts'

package/src/pubsub/UCAN Specs Overview.md

@@ -0,0 +1,217 @@
+# UCAN Specifications and Implementations (2026 Overview)
+
+[via Perplexity](https://www.perplexity.ai/search/ucan-specs-and-implementations-L_I1Xih5Se6CVF.FQS2rFQ)
+
+## Overview
+
+User Controlled Authorization Networks (UCANs) define a distributed, capability-based authorization system centered on verifiable delegation chains and decentralized identifiers (DIDs). The ecosystem consists of a core v1.0.0-rc.1 specification with several sub-specifications plus multiple language implementations at different maturity and spec levels.[^1][^2]
+
+## Core UCAN v1 Specification
+
+The main UCAN specification v1.0.0-rc.1 describes UCAN as a trustless, secure, local-first, user-originated distributed authorization scheme that uses certificate-style capabilities instead of ACLs. It defines a DAG-CBOR/IPLD-based envelope format with content-addressed CIDs, a cryptographic suite (Ed25519, P-256, secp256k1, SHA-256), and separates lifecycle stages into Delegation, Invocation, Promise, and Revocation sub-specs.[^1]
+
+### Key v1 design elements
+
+- Capabilities are modeled as triples of subject, command, and policy, capturing what a principal may do to which resource under which constraints.
+- Tokens are encoded as UCAN envelopes (signature bytes plus a signed payload with a type tag like `ucan/<subspec>@version`) instead of traditional JWTs.
+- Payloads include `iss`, `aud`, `sub`, `cmd`, `args`, `nonce`, optional `meta`, and time bounds `nbf`/`exp`, with validation rules over time, principal alignment, and signatures.
+
+## Delegation Sub-Specification
+
+The UCAN Delegation spec v1.0.0-rc.1 refines how attenuated authority is represented and delegated between principals. It uses the envelope tag `ucan/[email protected]` and defines a Delegation payload with issuer, audience, subject, command, policy, nonce, metadata, and time bounds.
+
+### Policy language and selectors
+
+Delegation introduces a syntactically driven policy language using predicate trees with operators such as equality, inequality, glob matching (`like`), logical connectives, and quantifiers (`all`/`any`). Policies constrain an eventual invocation’s `args` field using jq-inspired selectors (for example `.to[^1]`, `.a[0:2]`, `.field?`) that always resolve to IPLD values.
+
+### Powerline and resource model
+
+The spec defines a "Powerline" pattern where `sub: null` allows automatic redelegation of a user’s authority across devices, while still enforcing principal alignment, time bounds, and policy constraints. Resources are treated semantically, with the subject as the default resource, and external resources referenced via conditions in the policy.
+
+## Other v1 Sub-Specifications
+
+The main spec lists additional required or recommended sub-specifications: Delegation and Invocation are required, while Promise and Revocation are recommended for a complete lifecycle. Invocation describes how to exercise capabilities proven by delegations, Promise covers awaiting invocation results, and Revocation describes undoing delegations to break chains for malicious or compromised principals.[^3]
+
+## Pre‑v1 UCAN Specifications (JWT-Based)
+
+Before v1, the UCAN ecosystem used a JWT-based format where capabilities were carried in an `att` (attenuation) field and proof chains in a `prf` field. The gobengo/ucanto-spec repository documents UCAN Specification v0.8.1 using JWT headers with `alg` and a UCAN version field, and payload fields like `att`, `aud`, `exp`, `fct`, `iss`, `nbf`, and `prf`.[^4][^5]
+
+### Legacy library semantics
+
+The ucan-wg/ts-ucan TypeScript library mirrors this earlier spec, describing UCANs as JWTs with a header containing `alg`, `typ`, and `uav` (UCAN version), and a payload including `att`, `aud`, `exp`, `fct`, `iss`, `nbf`, and `prf`. Elixir’s ExUcan library similarly models JWT-based UCANs with header fields and payload fields such as `ucv` (version), `cap` (capabilities), `aud`, `exp`, `iss`, `nbf`, `prf`, and `nnc` (nonce).[^6][^7][^4]
+
+## Migration from JWT UCANs to v1 Envelope UCANs
+
+The UCAN Library Implementation Guide explains that v1.0.0-rc.1 introduces a new envelope format, IPLD/CBOR encoding, structured capabilities, a richer policy language, and distinct sub-specs, replacing the earlier JWT representation. Pull requests for the Delegation and Invocation specs emphasize the move to IPLD-based tokens and UCAN-specific type tags like `ucan/[email protected]` as part of this migration.[^8][^9][^3]
+
+### High-level differences
+
+- Encoding: legacy UCANs use JWT (base64url JSON), whereas v1 UCANs use CID-addressed DAG-CBOR/IPLD envelopes.[^5]
+- Capability model: legacy specs use `att` and `prf` arrays, while v1 organizes capabilities as subject/command/policy triples and separates Delegation from Invocation.[^5]
+- Policy: v0.x has relatively simple attenuation semantics; v1 adds a full predicate logic policy language with jq-style selectors and quantifiers.[^5]
+
+## Official UCAN Working Group Libraries
+
+The UCAN Working Group organization lists libraries in TypeScript (NPM), Rust (Crate), Golang, Haskell, JS IPLD helpers, and UCAN-RPC tools as the primary ecosystem components. It also notes additional specs like a UCAN container and classifies some older specs (HTTP bearer token, IPLD, JWT canonicalization) as outdated or obsolete.[^2]
+
+### Rust: rs-ucan and ucan crate
+
+The ucan-wg/rs-ucan repository hosts the Rust implementation, providing the `ucan` and `ucan-key-support` crates. The `ucan` crate offers a `UcanBuilder` abstraction for constructing signed tokens and a `ProofChain` for validating chains and reducing capabilities according to domain-specific semantics.[^10][^11]
+
+The `ucan-key-support` crate supplies ready-to-use `SigningKey` implementations compatible with the core crate, simplifying cryptographic integration. This stack targets the modern UCAN spec and is referenced from the main spec and the ucan.xyz site as the Rust implementation.[^12][^10]
+
+### Go: go-ucan
+
+The ucan-wg/go-ucan repository and its documentation describe a Go library designed to help web and decentralized applications integrate UCAN authorization flows. The library explicitly states that it supports the required parts of the UCAN specification—main spec, Delegation, and Invocation—while Revocation and Promise are not yet implemented.[^13][^14]
+
+Go-ucan integrates with a companion DID library (`go-did-it`), provides encrypted values in token metadata, and includes a UCAN container format for packaging multiple tokens together. The ucan.xyz Go library page reiterates this scope and positions go-ucan as the reference Go implementation.[^14][^13]
+
+### TypeScript (legacy): ts-ucan
+
+The ucan-wg/ts-ucan library implements the earlier JWT-based UCAN spec, emphasizing UCANs as JWTs with special keys, DIDs for issuer and audience, and offline/offline-friendly authorization flows. Its README walks through the header structure (`alg`, `typ`, `uav`) and payload fields for attenuation and proofs, matching the v0.8.x spec’s `att` and `prf` fields rather than the v1 envelope.[^4][^6][^5]
+
+## iso-ucan JavaScript Implementation
+
+Hugo Dias’s iso-ucan package (within the `hugomrdias/iso-repo` monorepo) is an isomorphic JavaScript implementation oriented around the v1 UCAN semantics. It is documented on ucan.xyz as the canonical JavaScript UCAN library and underpins the site’s examples and getting-started guides.[^15][^16]
+
+### API and semantics
+
+The iso-ucan README shows a usage pattern where capabilities are defined via `Capability.from({ schema, cmd })`, delegations are created with `Capability.delegate({ iss, aud, sub, pol, exp })`, and invocations are produced with `Capability.invoke({ iss, sub, args, store, exp })`. A `Store` abstraction backed by an `iso-kv` driver manages delegations, and signing uses EdDSA keys via `iso-signatures` (`EdDSASigner`).
+
+The ucan.xyz JavaScript library page and examples demonstrate the same patterns, using iso-ucan to define typed capabilities, delegate between identities, and create invocations with explicit command paths and argument schemas. This aligns closely with the v1 Delegation and Invocation specs’ focus on `cmd` paths, `pol` policy arrays, and argument-based validation.[^17][^15]
+
+## Substrate-System iso-ucan Fork
+
+The `substrate-system/iso-ucan` repository is a fork of Hugo Dias’s iso-ucan package, published on NPM as `@substrate-system/iso-ucan`. Its README states explicitly that it is a fork of `hugomrdias/iso-ucan` and focuses on packaging for different module systems and distribution formats.[^18]
+
+### Distribution and packaging differences
+
+The fork exposes both ESM and CommonJS entry points via the `exports` field, allowing import through either `import '@substrate-system/iso-ucan'` or `require('@substrate-system/iso-ucan')`. It also ships pre-built, minified JavaScript bundles (`dist/module.min.js`) that can be copied into a web server’s public directory and loaded via a `<script type="module" src="./module.min.js"></script>` tag.
+
+Functionally, the fork does not describe any behavioral divergence from upstream iso-ucan; it is presented as a repackaging intended to ease consumption in Substrate-related and browser contexts rather than a new spec variant.
+
+## Additional JavaScript Implementations
+
+Fission’s `@fission-codes/ucan` package provides another JavaScript UCAN library, offering a high-level `UCAN.create` API that accepts an issuer, audience, and a capabilities object mapping resources to allowed actions. The README points developers to Fission’s stack documentation for details and promotes dual Apache-2.0 and MIT licensing.[^19]
+
+The ucan.xyz examples and getting-started guide consistently highlight iso-ucan as the recommended JavaScript implementation for current v1 semantics. Legacy JWT-style libraries like ts-ucan remain useful for existing deployments but are not the focus of recent documentation.[^16][^15][^8][^4][^5]
+
+## Node.js Wrapper over Rust: @myjoypin/node-ucan
+
+The `@myjoypin/node-ucan` NPM package wraps the Rust rs-ucan library in a Node.js module, providing Node 18 binaries for common platforms and building from source elsewhere. Its documentation notes that it targets UCAN Specification v0.10.0, indicating that it lags behind the v1.0.0-rc.1 spec.[^20]
+
+The package demonstrates how UCANs can be used as bearer-style tokens and delegated without server involvement, with examples of a server delegating rights to Alice, and Alice delegating a subset of her rights to Bob using `invokeUcan` and `verifyUcan` helpers.[^20]
+
+## Other Community Implementations
+
+Beyond the core working-group libraries, there are several community UCAN implementations across languages. These typically implement older JWT-based specs or partial subsets of v1 features.[^21][^22]
+
+### Go community libraries
+
+The `github.com/qri-io/ucan` package provides an early Go implementation of UCAN tokens from Fission, describing them as an authenticated digraph in an authorization space and focusing on attenuation and delegation using nested capabilities. Documentation characterizes it as "under heavy construction" and associates it with Fission’s original whitepaper.[^23][^24]
+
+A separate `github.com/vibrantgenius/go-ucan` module advertises itself as aligned with UCAN v1.0.0-rc.1 and provides Go module packaging, though detailed documentation is limited in the high-level listing. The ucan-wg go-ucan library remains the primary reference implementation for current v1 semantics.[^25][^14]
+
+### Elixir and other languages
+
+The ExUcan library (Elixir) implements decentralized auth with UCANs, following the JWT-based model with header fields and payload fields including `ucv`, `cap`, `aud`, `exp`, `fct`, `nnc`, `iss`, `nbf`, and `prf`. Documentation highlights offline-first authorization and use of DIDs for issuer and audience, mirroring ts-ucan’s conceptual model.[^7]
+
+The UCAN Working Group’s organization page notes the existence of Haskell libraries and UCAN IPLD tooling in JavaScript, but detailed documentation for these was not surfaced in the high-level search results. They appear to be earlier or auxiliary efforts relative to the main Rust, Go, and iso-ucan stacks.[^22][^2]
+
+## UCAN Library Implementation Guide
+
+The UCAN Library Implementation Guide on ucan.xyz defines requirements for a complete v1 library: delegation creation and validation, invocation creation, capability management, cryptographic operations, and envelope handling. It emphasizes that v1 libraries must implement the envelope format, type tags, structured capabilities, IPLD/CBOR encoding, and the policy language.[^8]
+
+The guide lists major changes in v1, including the move away from JWT to UCAN-specific envelopes, structured capabilities that separate subject, command, and policy, and distinct Delegation, Invocation, Promise, and Revocation documents. This guidance underpins the design of rs-ucan, go-ucan, and iso-ucan as the v1-aligned libraries.[^8]
+
+## Comparison of Specifications
+
+### Specification-level differences
+
+| Aspect | v0.8.x JWT spec (ucanto-spec, ts-ucan, ExUcan) | v1.0.0-rc.1 UCAN spec and sub-specs |
+|-------|-----------------------------------------------|--------------------------------------|
+| Encoding | JWT (header, payload, signature as base64url JSON) | UCAN envelope: signature bytes plus IPLD DAG-CBOR payload addressed by CID |
+| Capability fields | `att` (attenuation list), `prf` (proof tokens), `cap` in some variants | `sub`, `cmd`, `pol` capabilities; `args` for invocation arguments |
+| Versioning | Header field (`uav`/`ucv`), overall spec version like v0.8.1 | Type tags `ucan/<subspec>@version` (for example `ucan/[email protected]`) and spec version 1.0.0-rc.1 |
+| Policy model | Simple attenuation semantics on `att` and basic field constraints | Full predicate policy language with comparison, glob, logical, and quantifier operators over jq-style selectors |
+| Lifecycle docs | Single spec describing tokens, plus whitepaper | Main spec plus Delegation, Invocation, Promise, Revocation specs with explicit lifecycle and validation rules |
+| Transport | JWT-focused, often HTTP bearer-centric | Transport-agnostic; tokens are IPLD objects identified by CIDs and may be transported via various mechanisms |
+
+Sources: v0.8.1 spec, ts-ucan, ExUcan, v1 spec, Delegation spec.[^7][^4][^5]
+
+## Comparison of Implementations
+
+### Library coverage and focus
+
+| Library | Language | Maintainer | Spec family | Encoding | Focus / Notes |
+|--------|----------|-----------|------------|----------|---------------|
+| iso-ucan | JavaScript/TypeScript | Hugo Dias | v1 Delegation/Invocation | IPLD/DAG-CBOR via UCAN envelopes | Isomorphic JS library with typed capabilities, EdDSA signing, and pluggable Stores; showcased on ucan.xyz as main JS library.[^15][^16] |
+| @substrate-system/iso-ucan | JavaScript/TypeScript | substrate-system | v1 (fork of iso-ucan) | Same as iso-ucan | Fork providing ESM/CJS exports and pre-built minified bundles for browser use; behavior follows upstream iso-ucan. |
+| ts-ucan | TypeScript | UCAN Working Group | v0.8.x JWT | JWT | Older library using JWT with `att`/`prf` payload; aligned with gobengo/ucanto v0.8.1 spec.[^4][^6][^5] |
+| @fission-codes/ucan | TypeScript | Fission | Legacy UCAN | Likely JWT (not explicitly stated) | High-level Fission stack library with `UCAN.create` helper and EdDSA signing; docs refer to Fission stack.[^19] |
+| ucan (Rust crate) | Rust | UCAN Working Group | v1 | UCAN envelope | Core Rust implementation with `UcanBuilder` and `ProofChain` for building and validating UCAN chains.[^10][^11] |
+| ucan-key-support | Rust | UCAN Working Group | v1 | UCAN envelope | Auxiliary crate providing ready-made `SigningKey` implementations for the Rust UCAN library.[^12] |
+| go-ucan (wg) | Go | UCAN Working Group | v1 (Delegation & Invocation) | UCAN envelope | Official Go implementation; supports main spec, Delegation, Invocation; Revocation and Promise to come; includes DID support and container format.[^13][^14] |
+| qri-io/ucan | Go | Qri | Early UCAN (JWT-style) | JWT | Early Go implementation of Fission’s UCAN tokens based on the whitepaper; marked under heavy construction.[^23][^24] |
+| @myjoypin/node-ucan | Node.js (Rust FFI) | Community | UCAN v0.10.0 | UCAN envelope / hybrid | Node bindings over rs-ucan; documented as targeting UCAN spec v0.10.0, with examples of delegation and verification in Node.[^20] |
+| ExUcan | Elixir | Community | v0.x JWT | JWT | Elixir library replicating JWT-based UCAN fields such as `ucv`, `cap`, `aud`, `exp`, `fct`, `nnc`, `iss`, `nbf`, `prf`.[^7] |
+
+## Practical Implications for Implementers
+
+For new projects, the v1.0.0-rc.1 spec family and corresponding libraries (iso-ucan, rs-ucan/ucan crate, and go-ucan) provide the most future-proof foundation, thanks to structured capabilities, a powerful policy language, and CID-addressed IPLD encoding. Developers integrating with existing JWT-based UCAN deployments may still rely on ts-ucan, ExUcan, or qri-io/ucan but should plan for migration if they want to interoperate with v1-only tooling.[^10][^14][^4][^7][^5]
+
+The substrate-system/iso-ucan fork is useful where bundling and module system support are primary concerns, since it repackages iso-ucan without altering semantics. Node environments needing Rust-level performance can use @myjoypin/node-ucan, but must be aware that it targets an earlier spec revision (v0.10.0) and may lack newer v1 features.[^20][^8]
+
+---
+
+## References
+
+1. [User Controlled Authorization Network (UCAN) Specification](https://ucan.xyz/specification/) - User-Controlled Authorization Network (UCAN) is a [trustless], secure, [local-first], user-originate...
+
+2. [UCAN Working Group](https://github.com/ucan-wg) - Decentralized Auth — User Controlled Authorization Networks - UCAN Working Group
+
+3. [v1.0.0-rc.1: High level invocation spec by expede · Pull Request #21 · ucan-wg/invocation](http://github.com/ucan-wg/invocation/pull/21) - Preview 📜 Supercedes V0.2 #15 TODOs Bump version to 1.0.0-rc.1 Closes Addressing individual task res...
+
+4. [ts-ucan/README.md at main - GitHub](https://github.com/ucan-wg/ts-ucan/blob/main/README.md) - UCANs are JWTs that contain special keys. At a high level, UCANs (“User Controlled Authorization Net...
+
+5. [GitHub - gobengo/ucanto-spec: User Controlled Authorization Network (UCAN) Specification](https://github.com/gobengo/ucanto-spec) - User Controlled Authorization Network (UCAN) Specification - gobengo/ucanto-spec
+
+6. [GitHub - ucan-wg/ts-ucan: Auth tokens for a distributed, user-controlled world](https://github.com/ucan-wg/ts-ucan) - Auth tokens for a distributed, user-controlled world - ucan-wg/ts-ucan
+
+7. [GitHub - spawnfest/youcan](https://github.com/spawnfest/youcan) - Contribute to spawnfest/youcan development by creating an account on GitHub.
+
+8. [UCAN Library Implementation Guide](https://ucan.xyz/libraries/implementation/) - A comprehensive guide for implementing UCAN libraries in different programming languages
+
+9. [v1.0.0-rc.1 by expede · Pull Request #2 · ucan-wg/delegation](http://github.com/ucan-wg/delegation/pull/2) - I may get pilloried for this version. WIP, obviously Preview 📚 Okay, this version switches to IPLD. ...
+
+10. [Crate ucan Copy item path](https://docs.rs/ucan/latest/ucan/) - Implement UCAN-based authorization with conciseness and ease!
+
+11. [rs-ucan/README.md at main · ucan-wg/rs-ucan](https://github.com/ucan-wg/rs-ucan/blob/main/README.md) - Rust implementation of UCAN. Contribute to ucan-wg/rs-ucan development by creating an account on Git...
+
+12. [ucan-key-support — Rust crypto library // Lib.rs](https://lib.rs/crates/ucan-key-support) - Ready to use SigningKey implementations for the ucan crate
+
+13. [GitHub - ucan-wg/go-ucan: User-Controlled Authorization Network (UCAN) tokens in go](https://github.com/ucan-wg/go-ucan) - User-Controlled Authorization Network (UCAN) tokens in go - ucan-wg/go-ucan
+
+14. [Go Implementation - UCAN](https://ucan.xyz/libraries/go/) - Documentation for Go Implementation
+
+15. [iso-ucan | UCAN](https://ucan.xyz/libraries/javascript/) - Documentation for iso-ucan.
+
+16. [Getting Started with UCAN](https://ucan.xyz/getting-started/) - import { Capability } from "iso-ucan/capability". import { EdDSASigner } ... User Controlled Authori...
+
+17. [UCAN Examples](https://ucan.xyz/guides/examples/) - Note: These examples use the v1.0.0-rc.1 UCAN specification and the iso-ucan JavaScript library. The...
+
+18. [@substrate-system/iso-ucan - npm](https://www.npmjs.com/package/@substrate-system%2Fiso-ucan) - UCAN. Latest version: 0.0.2, last published: 2 months ago. Start using @substrate-system/iso-ucan in...
+
+19. [@fission-codes/ucan](https://www.npmjs.com/package/@fission-codes/ucan?activeTab=readme) - UCAN (User Controlled Authorization Networks) is a decentralized authorization protocol for the web....
+
+20. [@myjoypin/node-ucan](https://www.npmjs.com/package/@myjoypin/node-ucan?activeTab=code) - UCAN for Node.js. Latest version: 0.1.0, last published: 10 months ago. Start using @myjoypin/node-u...
+
+21. [Build software better, together](https://github.com/topics/ucan) - GitHub is where people build software. More than 100 million people use GitHub to discover, fork, an...
+
+22. [Stabilizing the Object Capability System - ForgeFed](https://forgefed.org/blog/stabilizing-ocaps/) - Existing UCAN implementations in both Go (for Forgejo) and Haskell (for Vervis); Capabilities are cr...
+
+23. [README ¶](https://pkg.go.dev/github.com/dholms/ucan) - Package ucan implements User-Controlled Authorization Network tokens by fission: https://whitepaper....
+
+24. [ucan package - github.com/qri-io/ucan - Go Packages](https://pkg.go.dev/github.com/qri-io/ucan) - Package ucan implements User-Controlled Authorization Network tokens by fission: https://whitepaper....
+
+25. [go-ucan module - github.com/vibrantgenius/go-ucan - Go Packages](https://pkg.go.dev/github.com/vibrantgenius/go-ucan) - github.com/vibrantgenius/go-ucan. go-ucan. module ... go-ucan. UCAN v1.0.0-rc.1 GitHub Tag · Build S...

package/src/pubsub/connector.ts

@@ -0,0 +1,9 @@
+import { CarReader } from '@ipld/car'
+import { CID } from 'multiformats'
+
+export interface StorageConnector {
+	storeCar(car: Blob, signal?: AbortSignal): Promise<CID>
+}
+export interface RetrievalConnector {
+	retrieveCar(cid: CID): Promise<CarReader>
+}

package/src/pubsub/pub-pull.ts

@@ -0,0 +1,31 @@
+import { Logger } from 'besonders-logger'
+import { CID } from 'multiformats'
+import { ensureTsPvAndFinalizeApplog } from '../applog/applog-helpers.ts'
+import { EntityID } from '../applog/datom-types.ts'
+import { Thread } from '../thread.ts'
+
+const { WARN, LOG, DEBUG, VERBOSE, ERROR } = Logger.setup(Logger.INFO) // eslint-disable-line no-unused-vars
+
+export type PubPullData = {
+	cid: CID
+	thread: Thread
+}
+
+export function integratePub({ targetThread, agentHash, subID, pubData }: {
+	targetThread: Thread
+	agentHash: EntityID
+	pubData: PubPullData
+	subID?: EntityID
+}) {
+	const newLogs = pubData.thread.applogs.filter(log => !targetThread.hasApplog(log, false))
+	DEBUG(`[integratePub] integrating ${newLogs.length} logs`, { targetThread, subID, pubData })
+	let toInsert = newLogs
+	if (subID) {
+		toInsert = toInsert.concat(ensureTsPvAndFinalizeApplog(
+			{ en: subID, at: 'subscription/cid', vl: pubData.cid.toString(), ag: agentHash },
+			targetThread,
+		))
+	}
+	targetThread.insertRaw(toInsert)
+	return newLogs
+}

package/src/pubsub/pubsub-types.ts

@@ -0,0 +1,90 @@
+import { CID } from 'multiformats/cid'
+import { cyrb53hash } from './../applog/applog-utils.ts'
+import { AgentHash, AgentID, CidString } from '../applog/datom-types.ts'
+import { Tagged } from '../types.ts'
+import { UCANCapMap } from './ucan.ts'
+type AgentString = Tagged<string, 'AgentString'>
+type DIDString = Tagged<string, 'DID'>
+export type { AgentHash, AgentString, DIDString }
+
+
+export interface AppAgent {
+	ag: AgentHash
+	agentString: AgentString
+	did: DIDString
+	sign? (data: Uint8Array): Promise<Uint8Array>
+	ucan?: UCANCapMap
+}
+export interface AppAgentForWorker extends AppAgent {
+	signerSecret?: Uint8Array
+}
+export interface SnapRootBlock {
+	applogs: CID
+	applogsSignature: Uint8Array
+	info: CID
+	infoSignature: Uint8Array
+	prev?: CID
+	prevCounter?: number | null  // Sequential counter: 0 for first, then +1 for each. null = unknown (legacy/error).
+}
+export interface SnapBlockLogs {
+	logs: CID[]
+}
+export interface SnapBlockChunks {
+	chunks: CID[]
+}
+export type SnapBlockLogsOrChunks = SnapBlockLogs | SnapBlockChunks
+
+// HACK: this is actually note3 types, not wovin
+export interface IShare {
+	id?: string // string hash of pub (used as unique id in IDB) `W3Name.create().toString()` starts with k51qzi5uqu5d
+	createdAt: string // ISO timestamp of creation
+	name: string // nick name for the pub
+	isDeleted?: boolean
+	purgeBeforePush?: boolean
+
+	pk: Uint8Array // exported privatekey - needed to create WritableName for publishing //TODO: store as non-extractable / encrypted?
+
+	autopush: boolean
+	lastPush: string | null
+	lastCID?: string
+	latestLogTs?: string
+	pubCounter?: number
+
+	publishedBy: string // local user appAgent
+	selectors?: string[] // to be used as a filter for which applogs to pub
+	encryptedFor?: string | null // short agentHash
+	encryptedWith?: CryptoKey | null // AES-GCM derived key from ECDH keys (local private and remote public)
+
+	// HACK WIP #39 - shared encryption
+	sharedKey?: CryptoKey | null // AES-GCM derived key from ECDH keys (local private and ipns public)
+	sharedAgents?: AgentID[] | null // array of string EntityIDs for the chosen agents (we need public jwkd atoms for each of them)
+	sharedKeyMap?: Map<AgentID, string> | null // uses public key from each agent to derive an aes key that is used to encrypt and btoa the sharedKey that is actually used to encrypt and decrypt the applogs
+}
+export interface ISubscription {
+	id: string // string hash of pub (used as unique id in IDB) `W3Name.create().toString()` starts with k51qzi5uqu5d
+	createdAt: string // ISO timestamp of creation
+	name: string // nick name for the pub
+	isDeleted: boolean
+
+	lastPull?: string | null
+	lastPullAttempt?: string | null
+	autopull: boolean
+	realtime?: boolean // enable real-time WebSocket updates via IPNS watcher
+	lastCID?: string // ? why not CidString
+	lastApplogCID?: string
+	publishedBy?: string // remote publisher short agentHash
+	encryptedFor?: string | undefined // short agentHash
+	encryptedWith?: CryptoKey | undefined // AES-GCM derived key from ECDH keys (local private and remote public)
+}
+export function isShare(obj: any): obj is IShare {
+	return obj?.pk !== undefined && obj?.lastPush !== undefined
+}
+export function isSubscription(obj: any): obj is ISubscription {
+	return obj?.lastPull !== undefined
+}
+
+export type TShareSub = IShare | ISubscription
+
+export function agentToShortHash(agentString: string) {
+	return cyrb53hash(agentString, 31, 7) as string
+}