microfed 0.0.12 → 0.0.14

package/README.md

@@ -3,80 +3,209 @@
   <h1><a href="https://microfed.org/">Microfed</a></h1>
 </div>
 
-<div align="center">  
-<i>Micro Services Meets the Fediverse</i>
+<div align="center">
+<i>Minimal, modular ActivityPub microservices</i>
 </div>
 
 ---
 
-<div align="center">
-<h4>Documentation</h4>
-</div>
-  
----
-  
 [![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/micro-fed/microfed.org/blob/gh-pages/LICENSE)
 [![npm](https://img.shields.io/npm/v/microfed)](https://npmjs.com/package/microfed)
 [![npm](https://img.shields.io/npm/dw/microfed.svg)](https://npmjs.com/package/microfed)
 [![Github Stars](https://img.shields.io/github/stars/micro-fed/microfed.org.svg)](https://github.com/micro-fed/microfed.org/)
-  
-# ⚡️ Introduction
-
-This project is still at concept stage and aims to brainstorm the intersection of [micro services](https://en.wikipedia.org/wiki/Microservices) and the [fediverse](https://en.wikipedia.org/wiki/Fediverse).
-
-# 🎨 Design
-
-Microfed follows a modular design approach, ensuring flexibility and maintainability. The high-level design focuses on the interaction between microservices and the fediverse.
-
-The idea is that each component of a fediverse server can be composed from smaller services.
-
-These include:
-- [Profile](#Profile)
-- [Inbox](#Inbox)
-- [Outbox](#Outbox)
-- [Authentication](#Authentication)
-
-[Design Documentation](./DESIGN.md)
-
-
-# ✍️ Profile
-
-Your Profile page is the starting point for microfed services.  It will generally be an HTTP page, but the data should be agnostic to HTTP or any other protocol so that it can live in a database, or run over a P2P network.
-
-The Profile will be in HTML, with the data in in JSON(-LD).  It will contain:
-
-&nbsp;&nbsp;✓&nbsp;The Profile page  
-&nbsp;&nbsp;✓&nbsp;The User / Actor / Agent  
-&nbsp;&nbsp;✓&nbsp;Attributes about the User  
-&nbsp;&nbsp;✓&nbsp;Ability to store a public key  
-&nbsp;&nbsp;✓&nbsp;A list of connections (friends, knows, followers etc.)  
-&nbsp;&nbsp;✓&nbsp;Endpoint for Inbox  
-&nbsp;&nbsp;✓&nbsp;Endpoint for Outbox  
-&nbsp;&nbsp;✓&nbsp;Authentictation endpoints  
-&nbsp;&nbsp;✓&nbsp;Arbitrary fields specified by the user  
-
-The Profile can be self-hosted, or part of a multi user service.  It should be able to run on a mobile device, or in the browser.
-
-[Profile Design](./PROFILE.md)
-
-# 📬 Inbox
-
-The Inbox should be a place where people can send messages in JSON.  The micro service can filter out messages based on user preferences.  The message format should be as far as possible compatible with Activity Pub JSON.  Signatures can be used to verify the authenticity of a message.
-
-[Inbox Design](./INBOX.md)
-
-# 📤 Outbox
-
-The Outbox is a service that allows messages to be sent to other inboxes.  It should also have to ability to store a private key on behalf of a user, in order to sign outgoing messages.  It should be able to route messages to the right endpoints.
-
-[Outbox Design](./OUTBOX.md)
-
-# 🔐 Authentication
 
-Initially, strong authentication via PKI will be supported.  Delegated authentication, such as OAuth and OIDC may be considered desirable.  A loosely coupled authentication suite will allow the user to add different authentication modules.  This could also work with enterprise authentication. 
+## Features
+
+- **Pure JavaScript** — No TypeScript, no build step
+- **Zero dependencies** — Only Node.js built-ins
+- **Modular** — Use only what you need
+- **Fast** — Minimal overhead
+- **Standards compliant** — ActivityPub, WebFinger, HTTP Signatures
+
+## Install
+
+```bash
+npm install microfed
+```
+
+## Quick Start
+
+```javascript
+import { profile, auth, outbox } from 'microfed'
+
+// Generate keypair for signing
+const { publicKey, privateKey } = auth.generateKeypair()
+
+// Create an actor
+const actor = profile.createActor({
+  id: 'https://example.com/users/alice',
+  username: 'alice',
+  name: 'Alice',
+  publicKey
+})
+
+// Create a post
+const note = outbox.createNote({
+  actor: actor.id,
+  content: '<p>Hello, Fediverse!</p>'
+})
+
+// Wrap in Create activity
+const activity = outbox.wrapCreate(actor.id, note)
+
+// Send to a remote inbox
+await outbox.send({
+  activity,
+  inbox: 'https://remote.example/users/bob/inbox',
+  privateKey,
+  keyId: `${actor.id}#main-key`
+})
+```
+
+## Modules
+
+### profile — Actor generation
+
+```javascript
+import { createActor, createMinimalActor } from 'microfed/profile'
+
+const actor = createActor({
+  id: 'https://example.com/users/alice',
+  username: 'alice',
+  name: 'Alice',
+  summary: '<p>Hello!</p>',
+  publicKey: '-----BEGIN PUBLIC KEY-----...',
+  icon: 'https://example.com/avatar.png'
+})
+```
+
+### auth — Keypairs and HTTP Signatures
+
+```javascript
+import { generateKeypair, sign, verify } from 'microfed/auth'
+
+// Generate RSA keypair
+const { publicKey, privateKey } = generateKeypair()
+
+// Sign a request
+const headers = sign({
+  privateKey,
+  keyId: 'https://example.com/users/alice#main-key',
+  method: 'POST',
+  url: 'https://remote.example/inbox',
+  body: JSON.stringify(activity)
+})
+
+// Verify incoming signature
+const valid = verify({
+  publicKey,
+  signature: req.headers.signature,
+  method: 'POST',
+  path: '/inbox',
+  headers: req.headers
+})
+```
+
+### webfinger — Discovery
+
+```javascript
+import { createResponse, lookup, resolve } from 'microfed/webfinger'
+
+// Create WebFinger response
+const response = createResponse(
+  'alice@example.com',
+  'https://example.com/users/alice'
+)
+
+// Lookup remote actor
+const actor = await resolve('bob@remote.example')
+```
+
+### inbox — Receive activities
+
+```javascript
+import { createHandler } from 'microfed/inbox'
+
+const handler = createHandler({
+  getPublicKey: async (keyId) => {
+    // Fetch and return public key for keyId
+  },
+  handlers: {
+    Follow: async (activity) => {
+      console.log(`Follow from ${activity.actor}`)
+    },
+    Create: async (activity) => {
+      console.log(`New post: ${activity.object.content}`)
+    }
+  }
+})
+```
+
+### outbox — Send activities
+
+```javascript
+import { createNote, createFollow, send, deliver } from 'microfed/outbox'
+
+// Create a post
+const note = createNote({
+  actor: 'https://example.com/users/alice',
+  content: '<p>Hello!</p>'
+})
+
+// Create a follow
+const follow = createFollow(
+  'https://example.com/users/alice',
+  'https://remote.example/users/bob'
+)
+
+// Deliver to multiple inboxes
+const results = await deliver({
+  activity,
+  inboxes: ['https://server1.example/inbox', 'https://server2.example/inbox'],
+  privateKey,
+  keyId: 'https://example.com/users/alice#main-key'
+})
+```
+
+## Example Server
+
+Run the demo server:
+
+```bash
+npm run example
+# → http://localhost:3000
+```
+
+Test it:
+
+```bash
+# WebFinger
+curl "http://localhost:3000/.well-known/webfinger?resource=acct:alice@localhost:3000"
+
+# Actor
+curl -H "Accept: application/activity+json" http://localhost:3000/users/alice
+```
+
+## Testing
+
+```bash
+npm test
+```
+
+## Design
+
+Microfed decomposes a fediverse server into modular microservices:
+
+| Module | Purpose |
+|--------|---------|
+| **profile** | Actor/user representation |
+| **auth** | Cryptographic identity and signatures |
+| **webfinger** | Actor discovery |
+| **inbox** | Receive and process activities |
+| **outbox** | Create and send activities |
 
-[Authentication Design](./AUTHENTICATION.md)
+Each module can be used independently or combined. See the [Design Documentation](./DESIGN.md) for architecture details.
 
-# ⚖️ License
+## License
 
-- MIT
+MIT

package/example/server.js

@@ -0,0 +1,252 @@
+/**
+ * Microfed Example Server
+ * Minimal ActivityPub server using native Node.js http
+ *
+ * Run: node example/server.js
+ * Test: curl http://localhost:3000/.well-known/webfinger?resource=acct:alice@localhost:3000
+ */
+
+import { createServer } from 'http'
+import { profile, auth, webfinger, inbox } from '../index.js'
+
+// Configuration
+const PORT = process.env.PORT || 3000
+const DOMAIN = process.env.DOMAIN || `localhost:${PORT}`
+const PROTOCOL = DOMAIN.includes('localhost') ? 'http' : 'https'
+
+// Generate keypair for our actor
+const { publicKey, privateKey } = auth.generateKeypair()
+
+// Create our actor
+const actor = profile.createActor({
+  id: `${PROTOCOL}://${DOMAIN}/users/alice`,
+  username: 'alice',
+  name: 'Alice (Microfed Demo)',
+  summary: '<p>A demo actor running on Microfed</p>',
+  publicKey
+})
+
+// Store for received activities
+const activities = []
+const followers = []
+
+// Activity handlers
+const handlers = {
+  Follow: async (activity) => {
+    console.log(`Follow from: ${activity.actor}`)
+    followers.push(activity.actor)
+    // In production, you'd send an Accept activity back
+  },
+
+  Create: async (activity) => {
+    console.log(`Create: ${activity.object?.type}`)
+    activities.push(activity)
+  },
+
+  Like: async (activity) => {
+    console.log(`Like from: ${activity.actor}`)
+  },
+
+  Undo: async (activity) => {
+    console.log(`Undo: ${activity.object?.type}`)
+    if (activity.object?.type === 'Follow') {
+      const idx = followers.indexOf(activity.actor)
+      if (idx > -1) followers.splice(idx, 1)
+    }
+  }
+}
+
+// Get public key for signature verification
+async function getPublicKey(keyId) {
+  // In production, fetch the actor and extract publicKey
+  // For demo, we just return null (skip verification)
+  console.log(`Key lookup: ${keyId}`)
+  return null
+}
+
+// Create inbox handler
+const inboxHandler = inbox.createHandler({
+  getPublicKey,
+  handlers,
+  verifySignatures: false // Disable for local testing
+})
+
+// Request handler
+async function handleRequest(req, res) {
+  const url = new URL(req.url, `${PROTOCOL}://${DOMAIN}`)
+  const path = url.pathname
+  const accept = req.headers.accept || ''
+  const isActivityPub = accept.includes('activity+json') || accept.includes('ld+json')
+
+  console.log(`${req.method} ${path}`)
+
+  // CORS headers
+  res.setHeader('Access-Control-Allow-Origin', '*')
+  res.setHeader('Access-Control-Allow-Headers', '*')
+
+  if (req.method === 'OPTIONS') {
+    res.writeHead(204)
+    return res.end()
+  }
+
+  // WebFinger
+  if (path === '/.well-known/webfinger') {
+    const resource = url.searchParams.get('resource')
+    const parsed = webfinger.parseResource(resource)
+
+    if (!parsed || parsed.username !== 'alice') {
+      res.writeHead(404)
+      return res.end('Not found')
+    }
+
+    const response = webfinger.createResponse(
+      `alice@${DOMAIN}`,
+      actor.id,
+      { profileUrl: `${PROTOCOL}://${DOMAIN}/@alice` }
+    )
+
+    res.setHeader('Content-Type', 'application/jrd+json')
+    return res.end(JSON.stringify(response, null, 2))
+  }
+
+  // Actor profile
+  if (path === '/users/alice') {
+    res.setHeader('Content-Type', 'application/activity+json')
+    return res.end(JSON.stringify(actor, null, 2))
+  }
+
+  // Inbox
+  if (path === '/users/alice/inbox' && req.method === 'POST') {
+    // Convert Node request to Web Request for handler
+    const chunks = []
+    for await (const chunk of req) chunks.push(chunk)
+    const body = Buffer.concat(chunks).toString()
+
+    const webReq = new Request(url.href, {
+      method: 'POST',
+      headers: req.headers,
+      body
+    })
+
+    const webRes = await inboxHandler(webReq)
+    res.writeHead(webRes.status)
+    return res.end(await webRes.text())
+  }
+
+  // Outbox (read-only collection)
+  if (path === '/users/alice/outbox') {
+    const collection = {
+      '@context': 'https://www.w3.org/ns/activitystreams',
+      type: 'OrderedCollection',
+      id: `${actor.id}/outbox`,
+      totalItems: 0,
+      orderedItems: []
+    }
+    res.setHeader('Content-Type', 'application/activity+json')
+    return res.end(JSON.stringify(collection, null, 2))
+  }
+
+  // Followers collection
+  if (path === '/users/alice/followers') {
+    const collection = {
+      '@context': 'https://www.w3.org/ns/activitystreams',
+      type: 'OrderedCollection',
+      id: `${actor.id}/followers`,
+      totalItems: followers.length,
+      orderedItems: followers
+    }
+    res.setHeader('Content-Type', 'application/activity+json')
+    return res.end(JSON.stringify(collection, null, 2))
+  }
+
+  // Following collection
+  if (path === '/users/alice/following') {
+    const collection = {
+      '@context': 'https://www.w3.org/ns/activitystreams',
+      type: 'OrderedCollection',
+      id: `${actor.id}/following`,
+      totalItems: 0,
+      orderedItems: []
+    }
+    res.setHeader('Content-Type', 'application/activity+json')
+    return res.end(JSON.stringify(collection, null, 2))
+  }
+
+  // HTML profile page
+  if (path === '/@alice' || (path === '/users/alice' && !isActivityPub)) {
+    res.setHeader('Content-Type', 'text/html')
+    return res.end(`<!DOCTYPE html>
+<html>
+<head>
+  <title>${actor.name}</title>
+  <style>
+    body { font-family: system-ui; max-width: 600px; margin: 2rem auto; padding: 1rem; }
+    .handle { color: #666; }
+  </style>
+</head>
+<body>
+  <h1>${actor.name}</h1>
+  <p class="handle">@alice@${DOMAIN}</p>
+  <p>${actor.summary}</p>
+  <p><strong>Followers:</strong> ${followers.length}</p>
+  <hr>
+  <p><small>Powered by <a href="https://microfed.org">Microfed</a></small></p>
+</body>
+</html>`)
+  }
+
+  // Home
+  if (path === '/') {
+    res.setHeader('Content-Type', 'text/html')
+    return res.end(`<!DOCTYPE html>
+<html>
+<head>
+  <title>Microfed Demo</title>
+  <style>
+    body { font-family: system-ui; max-width: 600px; margin: 2rem auto; padding: 1rem; }
+    code { background: #f0f0f0; padding: 0.2rem 0.4rem; border-radius: 3px; }
+    pre { background: #f0f0f0; padding: 1rem; overflow-x: auto; }
+  </style>
+</head>
+<body>
+  <h1>Microfed Demo Server</h1>
+  <p>A minimal ActivityPub server.</p>
+
+  <h2>Endpoints</h2>
+  <ul>
+    <li><a href="/.well-known/webfinger?resource=acct:alice@${DOMAIN}">WebFinger</a></li>
+    <li><a href="/users/alice">Actor (JSON)</a></li>
+    <li><a href="/@alice">Profile (HTML)</a></li>
+    <li><code>POST /users/alice/inbox</code> - Receive activities</li>
+  </ul>
+
+  <h2>Test with curl</h2>
+  <pre>curl -H "Accept: application/activity+json" ${PROTOCOL}://${DOMAIN}/users/alice</pre>
+
+  <p><a href="https://microfed.org">microfed.org</a></p>
+</body>
+</html>`)
+  }
+
+  res.writeHead(404)
+  res.end('Not found')
+}
+
+// Start server
+const server = createServer(handleRequest)
+
+server.listen(PORT, () => {
+  console.log(`
+  Microfed Demo Server
+  ====================
+  Running at: ${PROTOCOL}://${DOMAIN}
+
+  Endpoints:
+  - GET  /.well-known/webfinger?resource=acct:alice@${DOMAIN}
+  - GET  /users/alice
+  - POST /users/alice/inbox
+  - GET  /@alice
+
+  Try: curl -H "Accept: application/activity+json" ${PROTOCOL}://${DOMAIN}/users/alice
+  `)
+})

package/index.js

@@ -0,0 +1,36 @@
+/**
+ * Microfed - Minimal, modular ActivityPub microservices
+ *
+ * @example
+ * import { profile, auth, webfinger, inbox, outbox } from 'microfed'
+ *
+ * // Generate keypair
+ * const { publicKey, privateKey } = auth.generateKeypair()
+ *
+ * // Create actor
+ * const actor = profile.createActor({
+ *   id: 'https://example.com/users/alice',
+ *   username: 'alice',
+ *   name: 'Alice',
+ *   publicKey
+ * })
+ *
+ * // Create and send a post
+ * const note = outbox.createNote({
+ *   actor: actor.id,
+ *   content: '<p>Hello, Fediverse!</p>'
+ * })
+ * const activity = outbox.wrapCreate(actor.id, note)
+ */
+
+export * as profile from './src/profile.js'
+export * as auth from './src/auth.js'
+export * as webfinger from './src/webfinger.js'
+export * as inbox from './src/inbox.js'
+export * as outbox from './src/outbox.js'
+
+// Convenience re-exports
+export { createActor, createMinimalActor } from './src/profile.js'
+export { generateKeypair, sign, verify } from './src/auth.js'
+export { lookup, resolve } from './src/webfinger.js'
+export { createActivity, createNote, send, deliver } from './src/outbox.js'

package/package.json

@@ -1,10 +1,20 @@
 {
   "name": "microfed",
-  "version": "0.0.12",
-  "description": "microfed",
+  "version": "0.0.14",
+  "description": "Minimal, modular ActivityPub microservices",
+  "type": "module",
   "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./profile": "./src/profile.js",
+    "./auth": "./src/auth.js",
+    "./webfinger": "./src/webfinger.js",
+    "./inbox": "./src/inbox.js",
+    "./outbox": "./src/outbox.js"
+  },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "example": "node example/server.js",
+    "test": "node --test 'test/*.test.js'"
   },
   "repository": {
     "type": "git",
@@ -15,5 +25,13 @@
   "bugs": {
     "url": "https://github.com/micro-fed/microfed.org/issues"
   },
-  "homepage": "https://github.com/micro-fed/microfed.org#readme"
+  "homepage": "https://microfed.org",
+  "keywords": [
+    "activitypub",
+    "fediverse",
+    "microservices",
+    "federation",
+    "activitystreams",
+    "webfinger"
+  ]
 }