javascript-solid-server 0.0.96 → 0.0.97

package/README.md

@@ -18,6 +18,9 @@ A minimal, fast, JSON-LD native Solid server.
 - **HTTP Range Requests** - Partial content delivery for large files and media streaming
 - **Single-User Mode** - Simplified setup for personal pod servers
 - **ActivityPub Federation** - Fediverse integration with WebFinger, inbox/outbox, HTTP signatures
+- **Mastodon-compatible API** - Dynamic client registration, instance info, account verification
+- **OAuth 2.0 Authorization** - Shared auth flow for Mastodon clients, remoteStorage apps, and third-party panes
+- **remoteStorage Protocol** - [draft-dejong-remotestorage-22](https://remotestorage.io/spec/) file sync (requires `--activitypub` for WebFinger discovery + OAuth)
 - **LDP CRUD Operations** - GET, PUT, POST, DELETE, HEAD
 - **N3 Patch** - Solid's native patch format for RDF updates
 - **SPARQL Update** - Standard SPARQL UPDATE protocol for PATCH
@@ -554,6 +557,106 @@ curl -H "Accept: application/activity+json" http://localhost:3000/profile/card
 curl http://localhost:3000/.well-known/nodeinfo/2.1
 ```
 
+## Mastodon-compatible API
+
+JSS exposes Mastodon API endpoints so that Mastodon clients (Elk, Phanpy, Ice Cubes) can connect:
+
+```bash
+jss start --activitypub --idp
+```
+
+### Endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| `POST /api/v1/apps` | Dynamic client registration |
+| `GET /api/v1/accounts/verify_credentials` | Current user profile |
+| `GET /api/v1/instance` | Instance metadata |
+| `GET /oauth/authorize` | OAuth authorize page |
+| `POST /oauth/authorize` | Process login |
+| `POST /oauth/token` | Exchange code for Bearer token |
+
+### OAuth 2.0 Flow
+
+The OAuth layer is shared between Mastodon clients, remoteStorage apps, and third-party Solid panes:
+
+1. Client registers via `POST /api/v1/apps` (gets `client_id` + `client_secret`)
+2. Client redirects user to `GET /oauth/authorize?client_id=...&redirect_uri=...&response_type=code`
+3. User logs in, JSS redirects back with `?code=...`
+4. Client exchanges code for Bearer token via `POST /oauth/token`
+5. Bearer token works with all JSS endpoints (Solid, ActivityPub, remoteStorage)
+
+Supports out-of-band (OOB) redirect for CLI/desktop clients.
+
+### Testing
+
+```bash
+# Register a client
+curl -X POST http://localhost:3000/api/v1/apps \
+  -H "Content-Type: application/json" \
+  -d '{"client_name": "Test App", "redirect_uris": "urn:ietf:wg:oauth:2.0:oob"}'
+
+# Check instance info
+curl http://localhost:3000/api/v1/instance
+```
+
+## remoteStorage
+
+JSS implements the [remoteStorage protocol](https://remotestorage.io/spec/draft-dejong-remotestorage-22). The storage routes are always available, but WebFinger discovery and OAuth require `--activitypub` (which provides the WebFinger and OAuth endpoints). Any remoteStorage-compatible app can store and sync data on your pod.
+
+```bash
+jss start --activitypub --idp
+```
+
+### Discovery
+
+remoteStorage clients discover the storage endpoint via WebFinger:
+
+```bash
+curl "http://localhost:3000/.well-known/webfinger?resource=acct:me@localhost:3000"
+```
+
+The response includes a `remotestorage` link relation pointing to `/storage/me/`.
+
+### Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/storage/:user/*` | Read file or list folder (JSON-LD) |
+| `HEAD` | `/storage/:user/*` | Get metadata (ETag, Content-Type, size) |
+| `PUT` | `/storage/:user/*` | Write file (creates parent folders) |
+| `DELETE` | `/storage/:user/*` | Delete file |
+
+### How It Works
+
+- **Auth**: Bearer token via OAuth 2.0 (same flow as Mastodon clients)
+- **Public folder**: `/storage/me/public/*` is readable without auth
+- **Conditional requests**: If-Match, If-None-Match (uses shared ETag utilities)
+- **Dotfile protection**: `.acl`, `.meta`, and other dotfiles are blocked
+- **Read-only mode**: Respects `--read-only` flag
+- **Streaming**: Large files are streamed, not buffered
+
+### Testing
+
+```bash
+# Write a file (needs Bearer token from OAuth flow)
+curl -X PUT http://localhost:3000/storage/me/documents/hello.txt \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Content-Type: text/plain" \
+  -d "Hello, remoteStorage!"
+
+# Read it back
+curl -H "Authorization: Bearer YOUR_TOKEN" \
+  http://localhost:3000/storage/me/documents/hello.txt
+
+# List a folder
+curl -H "Authorization: Bearer YOUR_TOKEN" \
+  http://localhost:3000/storage/me/documents/
+
+# Read from public folder (no auth needed)
+curl http://localhost:3000/storage/me/public/readme.txt
+```
+
 ### Linking Nostr to WebID (did:nostr)
 
 Bridge your Nostr identity to a Solid WebID for seamless authentication:
@@ -1097,7 +1200,10 @@ src/
 │       ├── actor.js      # Actor JSON-LD
 │       ├── inbox.js      # Receive activities
 │       ├── outbox.js     # User's activities
-│       └── collections.js # Followers/following
+│       ├── collections.js # Followers/following
+│       ├── mastodon.js  # Mastodon API (apps, instance, verify_credentials)
+│       └── oauth.js     # OAuth 2.0 authorize/token flow
+├── remotestorage.js      # remoteStorage protocol (draft-dejong-remotestorage-22)
 ├── rdf/
 │   ├── turtle.js         # Turtle <-> JSON-LD
 │   └── conneg.js         # Content negotiation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "javascript-solid-server",
-  "version": "0.0.96",
+  "version": "0.0.97",
   "description": "A minimal, fast Solid server",
   "main": "src/index.js",
   "type": "module",

package/src/ap/index.js

@@ -10,6 +10,8 @@ import { createInboxHandler } from './routes/inbox.js'
 import { createOutboxHandler, createOutboxPostHandler } from './routes/outbox.js'
 import { createCollectionsHandler } from './routes/collections.js'
 import { createActorHandler } from './routes/actor.js'
+import { createAppsHandler, createVerifyCredentialsHandler, createInstanceHandler } from './routes/mastodon.js'
+import { createAuthorizeHandler, createAuthorizePostHandler, createTokenHandler } from './routes/oauth.js'
 
 // Shared state for actor handler (accessed by server.js)
 let sharedActorHandler = null
@@ -106,6 +108,17 @@ export async function activityPubPlugin(fastify, options = {}) {
       { profileUrl }
     )
 
+    // Add remoteStorage link relation
+    response.links.push({
+      rel: 'http://tools.ietf.org/id/draft-dejong-remotestorage',
+      href: `${baseUrl}/storage/${config.username}/`,
+      properties: {
+        'http://remotestorage.io/spec/version': 'draft-dejong-remotestorage-22',
+        'http://tools.ietf.org/html/rfc6749#section-4.2': `${baseUrl}/oauth/authorize`,
+        'http://tools.ietf.org/html/rfc6750#section-2.3': 'Bearer'
+      }
+    })
+
     return reply
       .header('Content-Type', 'application/jrd+json')
       .header('Access-Control-Allow-Origin', '*')
@@ -135,7 +148,7 @@ export async function activityPubPlugin(fastify, options = {}) {
         version: '2.1',
         software: {
           name: 'jss',
-          version: '0.0.67',
+          version: '0.0.97',
           repository: 'https://github.com/JavaScriptSolidServer/JavaScriptSolidServer'
         },
         protocols: ['activitypub', 'solid'],
@@ -173,6 +186,32 @@ export async function activityPubPlugin(fastify, options = {}) {
   const collectionsHandler = createCollectionsHandler(config)
   fastify.get('/profile/card/followers', (req, reply) => collectionsHandler(req, reply, 'followers'))
   fastify.get('/profile/card/following', (req, reply) => collectionsHandler(req, reply, 'following'))
+
+  // Mastodon-compatible API endpoints
+  fastify.post('/api/v1/apps', createAppsHandler())
+  fastify.get('/api/v1/accounts/verify_credentials', createVerifyCredentialsHandler(config))
+  fastify.get('/api/v1/instance', createInstanceHandler(config))
+
+  // OAuth 2.0 authorize/token flow (Mastodon clients, remoteStorage, third-party panes)
+  fastify.get('/oauth/authorize', createAuthorizeHandler())
+  fastify.post('/oauth/authorize', {
+    config: {
+      rateLimit: {
+        max: 10,
+        timeWindow: '1 minute',
+        keyGenerator: (request) => request.ip
+      }
+    }
+  }, createAuthorizePostHandler())
+  fastify.post('/oauth/token', {
+    config: {
+      rateLimit: {
+        max: 10,
+        timeWindow: '1 minute',
+        keyGenerator: (request) => request.ip
+      }
+    }
+  }, createTokenHandler())
 }
 
 export default activityPubPlugin

package/src/ap/routes/mastodon.js

@@ -0,0 +1,154 @@
+/**
+ * Mastodon-compatible API endpoints
+ * Allows Mastodon clients (Elk, Phanpy, Ice Cubes) to connect to JSS
+ *
+ * Step 1: Dynamic client registration + account verification
+ * Refs: https://docs.joinmastodon.org/methods/apps/
+ *       https://docs.joinmastodon.org/methods/accounts/#verify_credentials
+ */
+
+// In-memory client store (replace with persistent storage later)
+const clients = new Map()
+
+// Stable instance start time (used for created_at)
+const startedAt = new Date().toISOString()
+
+/**
+ * Parse request body — handles both JSON and form-urlencoded
+ * (JSS uses raw buffer parser for all content types)
+ */
+function parseBody (request) {
+  if (request.body && typeof request.body === 'object' && !Buffer.isBuffer(request.body)) {
+    return request.body
+  }
+  const raw = Buffer.isBuffer(request.body) ? request.body.toString() : String(request.body || '')
+  const ct = request.headers['content-type'] || ''
+  if (ct.includes('application/json')) {
+    try { return JSON.parse(raw) } catch { return {} }
+  }
+  // Default: parse as form-urlencoded
+  return Object.fromEntries(new URLSearchParams(raw))
+}
+
+/**
+ * POST /api/v1/apps — Dynamic client registration
+ * Mastodon clients call this to register before OAuth
+ */
+export function createAppsHandler () {
+  return async (request, reply) => {
+    const body = parseBody(request)
+    const { client_name, redirect_uris, scopes, website } = body
+
+    if (!client_name || !redirect_uris) {
+      return reply.code(422).send({ error: 'client_name and redirect_uris are required' })
+    }
+
+    const clientId = crypto.randomUUID()
+    const clientSecret = crypto.randomUUID()
+
+    const client = {
+      id: clientId,
+      name: client_name,
+      redirect_uri: redirect_uris,
+      client_id: clientId,
+      client_secret: clientSecret,
+      scopes: scopes || 'read',
+      website: website || null
+    }
+
+    clients.set(clientId, client)
+
+    return reply.send(client)
+  }
+}
+
+/**
+ * GET /api/v1/accounts/verify_credentials — Who am I?
+ * Returns the authenticated user's profile as a Mastodon Account object
+ */
+export function createVerifyCredentialsHandler (config) {
+  return async (request, reply) => {
+    const protocol = request.headers['x-forwarded-proto'] || request.protocol
+    const host = request.headers['x-forwarded-host'] || request.hostname
+    const baseUrl = `${protocol}://${host}`
+
+    const account = {
+      id: '1',
+      username: config.username,
+      acct: config.username,
+      display_name: config.displayName,
+      note: config.summary ? `<p>${escapeHtml(config.summary)}</p>` : '',
+      url: `${baseUrl}/profile/card`,
+      uri: `${baseUrl}/profile/card#me`,
+      avatar: `${baseUrl}/profile/avatar.png`,
+      header: '',
+      locked: false,
+      bot: false,
+      created_at: startedAt,
+      followers_count: 0,
+      following_count: 0,
+      statuses_count: 0,
+      source: {
+        privacy: 'public',
+        sensitive: false,
+        language: 'en',
+        note: config.summary || ''
+      }
+    }
+
+    return reply.send(account)
+  }
+}
+
+/**
+ * GET /api/v1/instance — Instance information
+ * Required by most Mastodon clients before login
+ */
+export function createInstanceHandler (config) {
+  return async (request, reply) => {
+    const protocol = request.headers['x-forwarded-proto'] || request.protocol
+    const host = request.headers['x-forwarded-host'] || request.hostname
+    const wsProtocol = protocol === 'https' ? 'wss' : 'ws'
+
+    return reply.send({
+      uri: host,
+      title: config.displayName || 'JSS',
+      description: 'SAND Stack: Solid + ActivityPub + Nostr + DID',
+      short_description: 'Solid pod with Mastodon-compatible API',
+      version: '4.0.0 (compatible; JSS 0.0.97)',
+      urls: {
+        streaming_api: `${wsProtocol}://${host}`
+      },
+      stats: {
+        user_count: 1,
+        status_count: 0,
+        domain_count: 1
+      },
+      languages: ['en'],
+      registrations: false,
+      approval_required: false,
+      configuration: {
+        statuses: { max_characters: 5000 },
+        media_attachments: { supported_mime_types: [] }
+      }
+    })
+  }
+}
+
+/**
+ * Look up a registered client
+ */
+export function getClient (clientId) {
+  return clients.get(clientId) || null
+}
+
+function escapeHtml (str) {
+  return str.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;')
+}
+
+export default {
+  createAppsHandler,
+  createVerifyCredentialsHandler,
+  createInstanceHandler,
+  getClient
+}

package/src/ap/routes/oauth.js

@@ -0,0 +1,284 @@
+/**
+ * OAuth 2.0 authorize/token flow
+ * Shared infrastructure for Mastodon clients, remoteStorage apps, and third-party panes
+ *
+ * Refs: https://docs.joinmastodon.org/methods/oauth/
+ *       https://datatracker.ietf.org/doc/html/rfc6749
+ *
+ * Related: #158, #159 (Mastodon API), #106 (remoteStorage), #160 (this)
+ */
+
+import crypto from 'crypto'
+import { getClient } from './mastodon.js'
+import { authenticate } from '../../idp/accounts.js'
+import { createToken } from '../../auth/token.js'
+
+// Mastodon OOB redirect — display code instead of redirecting
+const OOB_REDIRECT = 'urn:ietf:wg:oauth:2.0:oob'
+
+// Auth codes: code → { clientId, redirectUri, webId, scope, expiresAt }
+const authCodes = new Map()
+
+// Clean up expired codes every 60s
+setInterval(() => {
+  const now = Date.now()
+  for (const [code, data] of authCodes) {
+    if (data.expiresAt < now) authCodes.delete(code)
+  }
+}, 60000).unref()
+
+/**
+ * Parse request body — handles JSON and form-urlencoded
+ */
+function parseBody (request) {
+  if (request.body && typeof request.body === 'object' && !Buffer.isBuffer(request.body)) {
+    return request.body
+  }
+  const raw = Buffer.isBuffer(request.body) ? request.body.toString() : String(request.body || '')
+  const ct = request.headers['content-type'] || ''
+  if (ct.includes('application/json')) {
+    try { return JSON.parse(raw) } catch { return {} }
+  }
+  return Object.fromEntries(new URLSearchParams(raw))
+}
+
+/**
+ * Validate client_id and redirect_uri against registered client
+ * Returns { client, error } — client is null if validation fails
+ */
+function validateClient (clientId, redirectUri) {
+  if (!clientId || !redirectUri) {
+    return { client: null, error: 'Missing client_id or redirect_uri' }
+  }
+
+  const client = getClient(clientId)
+  if (!client) {
+    return { client: null, error: 'Unknown client_id. Register via POST /api/v1/apps first.' }
+  }
+
+  // Validate redirect_uri matches registered value (RFC 6749 §10.6)
+  if (redirectUri !== OOB_REDIRECT && redirectUri !== client.redirect_uri) {
+    return { client: null, error: 'redirect_uri does not match registered value' }
+  }
+
+  return { client, error: null }
+}
+
+/**
+ * GET /oauth/authorize — Show login/consent page
+ */
+export function createAuthorizeHandler () {
+  return async (request, reply) => {
+    const { client_id, redirect_uri, response_type, scope, state } = request.query
+
+    if (response_type && response_type !== 'code') {
+      return reply.code(400).send({ error: 'unsupported_response_type', error_description: 'Only response_type=code is supported' })
+    }
+
+    const { client, error } = validateClient(client_id, redirect_uri)
+    if (!client) {
+      return reply.code(400).send({ error: 'invalid_client', error_description: error })
+    }
+
+    return reply.type('text/html').send(
+      loginPage({ clientId: client_id, redirectUri: redirect_uri, scope: scope || 'read', state, clientName: client.name })
+    )
+  }
+}
+
+/**
+ * POST /oauth/authorize — Process login form
+ */
+export function createAuthorizePostHandler () {
+  return async (request, reply) => {
+    const body = parseBody(request)
+    const { username, password, client_id, redirect_uri, scope, state } = body
+
+    // Validate client + redirect_uri (prevent open redirect via form tampering)
+    const { client, error: clientError } = validateClient(client_id, redirect_uri)
+    if (!client) {
+      return reply.code(400).send({ error: 'invalid_client', error_description: clientError })
+    }
+
+    if (!username || !password) {
+      return reply.type('text/html').send(
+        loginPage({ clientId: client_id, redirectUri: redirect_uri, scope, state, clientName: client.name, error: 'Username and password are required' })
+      )
+    }
+
+    const account = await authenticate(username, password)
+    if (!account) {
+      return reply.type('text/html').send(
+        loginPage({ clientId: client_id, redirectUri: redirect_uri, scope, state, clientName: client.name, error: 'Invalid username or password' })
+      )
+    }
+
+    // Generate one-time auth code (10 min TTL)
+    const code = crypto.randomUUID()
+    authCodes.set(code, {
+      clientId: client_id,
+      redirectUri: redirect_uri,
+      webId: account.webId,
+      scope: scope || 'read',
+      expiresAt: Date.now() + 600_000
+    })
+
+    // Handle OOB redirect — display code to user instead of redirecting
+    if (redirect_uri === OOB_REDIRECT) {
+      return reply.type('text/html').send(oobPage(code))
+    }
+
+    // Redirect back to client with code + state (RFC 6749 §4.1.2)
+    const url = new URL(redirect_uri)
+    url.searchParams.set('code', code)
+    if (state) url.searchParams.set('state', state)
+    return reply.redirect(url.toString())
+  }
+}
+
+/**
+ * POST /oauth/token — Exchange auth code for Bearer token
+ */
+export function createTokenHandler () {
+  return async (request, reply) => {
+    const body = parseBody(request)
+    const { grant_type, code, client_id, client_secret, redirect_uri } = body
+
+    if (grant_type !== 'authorization_code') {
+      return reply.code(400).send({ error: 'unsupported_grant_type' })
+    }
+
+    if (!code) {
+      return reply.code(400).send({ error: 'invalid_request', error_description: 'Missing code' })
+    }
+
+    // Validate client credentials (RFC 6749 §2.3)
+    const client = getClient(client_id)
+    if (!client) {
+      return reply.code(401).send({ error: 'invalid_client', error_description: 'Unknown client_id' })
+    }
+    try {
+      if (!crypto.timingSafeEqual(Buffer.from(client.client_secret), Buffer.from(client_secret || ''))) {
+        return reply.code(401).send({ error: 'invalid_client', error_description: 'Invalid client_secret' })
+      }
+    } catch {
+      return reply.code(401).send({ error: 'invalid_client', error_description: 'Invalid client_secret' })
+    }
+
+    // Look up auth code and consume immediately (RFC 6749 §10.5 — one-time use)
+    const authCode = authCodes.get(code)
+    authCodes.delete(code)
+
+    if (!authCode || authCode.expiresAt < Date.now()) {
+      return reply.code(400).send({ error: 'invalid_grant', error_description: 'Code expired or invalid' })
+    }
+
+    if (authCode.clientId !== client_id) {
+      return reply.code(400).send({ error: 'invalid_client' })
+    }
+
+    if (authCode.redirectUri !== redirect_uri) {
+      return reply.code(400).send({ error: 'invalid_grant', error_description: 'redirect_uri mismatch' })
+    }
+
+    // Generate Bearer token using existing token infrastructure
+    const accessToken = createToken(authCode.webId)
+
+    return reply.send({
+      access_token: accessToken,
+      token_type: 'Bearer',
+      scope: authCode.scope,
+      created_at: Math.floor(Date.now() / 1000)
+    })
+  }
+}
+
+/**
+ * Minimal login page HTML
+ */
+function loginPage ({ clientId, redirectUri, scope, state, clientName, error }) {
+  const escapedError = error ? escapeHtml(error) : ''
+  const escapedName = escapeHtml(clientName || clientId || 'Unknown app')
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Authorize ${escapedName}</title>
+  <style>
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+    body { font-family: -apple-system, BlinkMacSystemFont, system-ui, sans-serif; background: #f5f5f5; display: flex; justify-content: center; align-items: center; min-height: 100vh; }
+    .card { background: white; border-radius: 12px; padding: 2rem; max-width: 400px; width: 90%; box-shadow: 0 2px 8px rgba(0,0,0,0.1); }
+    h1 { font-size: 1.25rem; margin-bottom: 0.5rem; }
+    .subtitle { color: #666; margin-bottom: 1.5rem; font-size: 0.9rem; }
+    .scope { background: #f0f0f0; padding: 0.5rem 0.75rem; border-radius: 6px; margin-bottom: 1.5rem; font-size: 0.85rem; color: #444; }
+    label { display: block; font-size: 0.85rem; font-weight: 500; margin-bottom: 0.25rem; color: #333; }
+    input[type="text"], input[type="password"] { width: 100%; padding: 0.6rem; border: 1px solid #ddd; border-radius: 6px; font-size: 1rem; margin-bottom: 1rem; }
+    input:focus { outline: none; border-color: #4a9eff; box-shadow: 0 0 0 2px rgba(74,158,255,0.2); }
+    button { width: 100%; padding: 0.7rem; background: #4a9eff; color: white; border: none; border-radius: 6px; font-size: 1rem; font-weight: 500; cursor: pointer; }
+    button:hover { background: #3a8eef; }
+    .error { background: #fee; color: #c00; padding: 0.6rem; border-radius: 6px; margin-bottom: 1rem; font-size: 0.85rem; }
+  </style>
+</head>
+<body>
+  <div class="card">
+    <h1>Authorize</h1>
+    <p class="subtitle"><strong>${escapedName}</strong> wants access to your account</p>
+    <div class="scope">Scope: ${escapeHtml(scope || 'read')}</div>
+    ${escapedError ? `<div class="error">${escapedError}</div>` : ''}
+    <form method="POST" action="/oauth/authorize">
+      <input type="hidden" name="client_id" value="${escapeHtml(clientId || '')}">
+      <input type="hidden" name="redirect_uri" value="${escapeHtml(redirectUri || '')}">
+      <input type="hidden" name="scope" value="${escapeHtml(scope || 'read')}">
+      ${state ? `<input type="hidden" name="state" value="${escapeHtml(state)}">` : ''}
+      <label for="username">Username</label>
+      <input type="text" id="username" name="username" required autocomplete="username">
+      <label for="password">Password</label>
+      <input type="password" id="password" name="password" required autocomplete="current-password">
+      <button type="submit">Authorize</button>
+    </form>
+  </div>
+</body>
+</html>`
+}
+
+/**
+ * OOB (out-of-band) code display page
+ * Used when redirect_uri is urn:ietf:wg:oauth:2.0:oob
+ */
+function oobPage (code) {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Authorization Code</title>
+  <style>
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+    body { font-family: -apple-system, BlinkMacSystemFont, system-ui, sans-serif; background: #f5f5f5; display: flex; justify-content: center; align-items: center; min-height: 100vh; }
+    .card { background: white; border-radius: 12px; padding: 2rem; max-width: 400px; width: 90%; box-shadow: 0 2px 8px rgba(0,0,0,0.1); text-align: center; }
+    h1 { font-size: 1.25rem; margin-bottom: 1rem; }
+    .code { background: #f0f0f0; padding: 1rem; border-radius: 6px; font-family: monospace; font-size: 0.9rem; word-break: break-all; user-select: all; }
+    p { color: #666; margin-top: 1rem; font-size: 0.85rem; }
+  </style>
+</head>
+<body>
+  <div class="card">
+    <h1>Authorization Successful</h1>
+    <div class="code">${escapeHtml(code)}</div>
+    <p>Copy this code and paste it into your application.</p>
+  </div>
+</body>
+</html>`
+}
+
+function escapeHtml (str) {
+  return String(str).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;')
+}
+
+export default {
+  createAuthorizeHandler,
+  createAuthorizePostHandler,
+  createTokenHandler
+}

package/src/remotestorage.js

@@ -0,0 +1,304 @@
+/**
+ * remoteStorage plugin for JSS
+ * Implements draft-dejong-remotestorage protocol on top of existing storage
+ *
+ * No new dependencies — reuses filesystem storage, OAuth, and WebFinger.
+ * Always on — no flag needed.
+ *
+ * Ref: https://remotestorage.io/spec/draft-dejong-remotestorage-22
+ * Related: #106, #160 (OAuth), #159 (Mastodon API)
+ */
+
+import * as storage from './storage/filesystem.js'
+import { getContentType } from './utils/url.js'
+import { getWebIdFromRequestAsync } from './auth/token.js'
+import { checkIfMatch, checkIfNoneMatchForGet, checkIfNoneMatchForWrite } from './utils/conditional.js'
+
+/**
+ * remoteStorage Fastify plugin
+ * @param {FastifyInstance} fastify
+ * @param {object} options
+ * @param {string} options.username - Storage owner username
+ * @param {string} options.ownerWebId - WebID of the storage owner
+ */
+export async function remoteStoragePlugin (fastify, options = {}) {
+  const username = options.username || 'me'
+  const ownerWebId = options.ownerWebId || null
+
+  /**
+   * Extract the storage path from the URL
+   * /storage/me/photos/vacation.jpg → /photos/vacation.jpg
+   */
+  function getStoragePath (request) {
+    const wildcard = request.params['*'] || ''
+    return '/' + wildcard
+  }
+
+  /**
+   * Check if the :user param matches the configured username
+   */
+  function checkUsername (request, reply) {
+    if (request.params.user !== username) {
+      reply.code(404).send({ error: 'Unknown user' })
+      return false
+    }
+    return true
+  }
+
+  /**
+   * Check if any path segment is a blocked dotfile
+   */
+  function hasDotfile (storagePath) {
+    const segments = storagePath.split('/')
+    return segments.some(s => s.startsWith('.') && s.length > 1)
+  }
+
+  /**
+   * Check if request is authorized for the given method
+   * Public folder is readable without auth
+   */
+  async function checkAuth (request, method) {
+    const storagePath = getStoragePath(request)
+
+    // Public folder: readable without auth
+    if (storagePath.startsWith('/public/') && (method === 'GET' || method === 'HEAD')) {
+      return { authorized: true, webId: null }
+    }
+
+    const { webId, error } = await getWebIdFromRequestAsync(request)
+    if (!webId) {
+      return { authorized: false, webId: null, error: error || 'Unauthorized', status: 401 }
+    }
+
+    // If ownerWebId is set, only the owner can access storage
+    if (ownerWebId && webId !== ownerWebId) {
+      return { authorized: false, webId, error: 'Forbidden', status: 403 }
+    }
+
+    return { authorized: true, webId }
+  }
+
+  // GET /storage/:user/* — read file or folder
+  fastify.get('/storage/:user/*', async (request, reply) => {
+    if (!checkUsername(request, reply)) return
+
+    const storagePath = getStoragePath(request)
+
+    // Block dotfile access
+    if (hasDotfile(storagePath)) {
+      return reply.code(404).send({ error: 'Not found' })
+    }
+
+    const { authorized, error, status } = await checkAuth(request, 'GET')
+    if (!authorized) {
+      const code = status || 401
+      if (code === 401) reply.header('WWW-Authenticate', 'Bearer')
+      return reply.code(code).send({ error })
+    }
+
+    const info = await storage.stat(storagePath)
+    if (!info) {
+      return reply.code(404).send({ error: 'Not found' })
+    }
+
+    // Conditional GET — use shared utility
+    const cond = checkIfNoneMatchForGet(request.headers['if-none-match'], info.etag)
+    if (!cond.ok) {
+      return reply.code(304).send()
+    }
+
+    // Directory listing
+    if (info.isDirectory) {
+      const entries = await storage.listContainer(storagePath)
+      if (!entries) {
+        return reply.code(404).send({ error: 'Not found' })
+      }
+
+      const items = {}
+      for (const entry of entries) {
+        // Skip dotfiles (ACLs, metadata, etc.)
+        if (entry.name.startsWith('.')) continue
+
+        const childPath = storagePath.endsWith('/') ? storagePath + entry.name : storagePath + '/' + entry.name
+        const childStat = await storage.stat(entry.isDirectory ? childPath + '/' : childPath)
+
+        if (entry.isDirectory) {
+          items[entry.name + '/'] = {
+            ETag: childStat?.etag?.replace(/"/g, '') || ''
+          }
+        } else {
+          items[entry.name] = {
+            ETag: childStat?.etag?.replace(/"/g, '') || '',
+            'Content-Type': getContentType(entry.name),
+            'Content-Length': childStat?.size || 0
+          }
+        }
+      }
+
+      return reply
+        .header('Content-Type', 'application/ld+json')
+        .header('ETag', info.etag)
+        .header('Cache-Control', 'no-cache')
+        .send({
+          '@context': 'http://remotestorage.io/spec/folder-description',
+          items
+        })
+    }
+
+    // File — stream instead of buffering
+    const result = storage.createReadStream(storagePath)
+    if (!result) {
+      return reply.code(404).send({ error: 'Not found' })
+    }
+
+    return reply
+      .header('Content-Type', getContentType(storagePath))
+      .header('Content-Length', info.size)
+      .header('ETag', info.etag)
+      .header('Cache-Control', 'no-cache')
+      .send(result.stream)
+  })
+
+  // HEAD /storage/:user/* — metadata only
+  fastify.head('/storage/:user/*', async (request, reply) => {
+    if (!checkUsername(request, reply)) return
+
+    const storagePath = getStoragePath(request)
+
+    if (hasDotfile(storagePath)) {
+      return reply.code(404).send()
+    }
+
+    const { authorized, error, status } = await checkAuth(request, 'HEAD')
+    if (!authorized) {
+      const code = status || 401
+      if (code === 401) reply.header('WWW-Authenticate', 'Bearer')
+      return reply.code(code).send()
+    }
+
+    const info = await storage.stat(storagePath)
+    if (!info) {
+      return reply.code(404).send()
+    }
+
+    // Conditional HEAD
+    const cond = checkIfNoneMatchForGet(request.headers['if-none-match'], info.etag)
+    if (!cond.ok) {
+      return reply.code(304).send()
+    }
+
+    reply
+      .header('Content-Type', info.isDirectory ? 'application/ld+json' : getContentType(storagePath))
+      .header('ETag', info.etag)
+      .header('Cache-Control', 'no-cache')
+
+    if (!info.isDirectory) {
+      reply.header('Content-Length', info.size)
+    }
+
+    return reply.code(200).send()
+  })
+
+  // PUT /storage/:user/* — write file
+  fastify.put('/storage/:user/*', async (request, reply) => {
+    if (!checkUsername(request, reply)) return
+
+    // Respect readOnly mode
+    if (request.config?.readOnly) {
+      return reply.code(405).send({ error: 'Method Not Allowed', message: 'Server is in read-only mode' })
+    }
+
+    const storagePath = getStoragePath(request)
+
+    if (hasDotfile(storagePath)) {
+      return reply.code(403).send({ error: 'Cannot write to dotfiles' })
+    }
+
+    const { authorized, error, status } = await checkAuth(request, 'PUT')
+    if (!authorized) {
+      const code = status || 401
+      if (code === 401) reply.header('WWW-Authenticate', 'Bearer')
+      return reply.code(code).send({ error })
+    }
+
+    // Directories end with / — can't PUT to a directory
+    if (storagePath.endsWith('/')) {
+      return reply.code(400).send({ error: 'Cannot PUT to a folder path' })
+    }
+
+    // Conditional write — use shared utilities
+    const existing = await storage.stat(storagePath)
+
+    const ifMatchResult = checkIfMatch(request.headers['if-match'], existing?.etag || null)
+    if (!ifMatchResult.ok) {
+      return reply.code(ifMatchResult.status).send({ error: ifMatchResult.error })
+    }
+
+    const ifNoneMatchResult = checkIfNoneMatchForWrite(request.headers['if-none-match'], existing?.etag || null)
+    if (!ifNoneMatchResult.ok) {
+      return reply.code(ifNoneMatchResult.status).send({ error: ifNoneMatchResult.error })
+    }
+
+    const content = Buffer.isBuffer(request.body) ? request.body : Buffer.from(request.body || '')
+    const success = await storage.write(storagePath, content)
+    if (!success) {
+      return reply.code(500).send({ error: 'Write failed' })
+    }
+
+    const newStat = await storage.stat(storagePath)
+    const statusCode = existing ? 200 : 201
+
+    return reply
+      .code(statusCode)
+      .header('ETag', newStat?.etag || '')
+      .send()
+  })
+
+  // DELETE /storage/:user/* — delete file
+  fastify.delete('/storage/:user/*', async (request, reply) => {
+    if (!checkUsername(request, reply)) return
+
+    // Respect readOnly mode
+    if (request.config?.readOnly) {
+      return reply.code(405).send({ error: 'Method Not Allowed', message: 'Server is in read-only mode' })
+    }
+
+    const storagePath = getStoragePath(request)
+
+    if (hasDotfile(storagePath)) {
+      return reply.code(403).send({ error: 'Cannot delete dotfiles' })
+    }
+
+    const { authorized, error, status } = await checkAuth(request, 'DELETE')
+    if (!authorized) {
+      const code = status || 401
+      if (code === 401) reply.header('WWW-Authenticate', 'Bearer')
+      return reply.code(code).send({ error })
+    }
+
+    const existing = await storage.stat(storagePath)
+    if (!existing) {
+      return reply.code(404).send({ error: 'Not found' })
+    }
+
+    // Conditional delete — use shared utility
+    const ifMatchResult = checkIfMatch(request.headers['if-match'], existing.etag)
+    if (!ifMatchResult.ok) {
+      return reply.code(ifMatchResult.status).send({ error: ifMatchResult.error })
+    }
+
+    const success = await storage.remove(storagePath)
+    if (!success) {
+      return reply.code(500).send({ error: 'Delete failed' })
+    }
+
+    return reply
+      .code(200)
+      .header('ETag', existing.etag)
+      .send()
+  })
+
+  fastify.log.info(`remoteStorage enabled for user: ${username}`)
+}
+
+export default remoteStoragePlugin

package/src/server.js

@@ -15,6 +15,7 @@ import { isGitRequest, isGitWriteOperation, handleGit } from './handlers/git.js'
 import { AccessMode } from './wac/parser.js';
 import { registerNostrRelay } from './nostr/relay.js';
 import { activityPubPlugin, getActorHandler } from './ap/index.js';
+import { remoteStoragePlugin } from './remotestorage.js';
 import { dbPlugin } from './db/index.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -234,6 +235,12 @@ export function createServer(options = {}) {
     });
   }
 
+  // Register remoteStorage plugin (always on — no flag needed)
+  fastify.register(remoteStoragePlugin, {
+    username: singleUserName || 'me',
+    ownerWebId: null  // single-user: any authenticated user can access
+  });
+
   // Register MongoDB /db/ route if enabled
   if (mongoEnabled) {
     fastify.register(dbPlugin, { mongoUrl, mongoDatabase, singleUser });
@@ -353,7 +360,9 @@ export function createServer(options = {}) {
   fastify.addHook('preHandler', async (request, reply) => {
     // Skip auth for pod creation, OPTIONS, IdP routes, mashlib, solidos-ui, well-known, notifications, nostr, git, and AP
     const mashlibPaths = ['/mashlib.min.js', '/mash.css', '/841.mashlib.min.js'];
-    const apPaths = ['/inbox', '/profile/card/inbox', '/profile/card/outbox', '/profile/card/followers', '/profile/card/following'];
+    const apPaths = ['/inbox', '/profile/card/inbox', '/profile/card/outbox', '/profile/card/followers', '/profile/card/following',
+      '/api/v1/apps', '/api/v1/instance', '/api/v1/accounts/verify_credentials',
+      '/oauth/authorize', '/oauth/token'];
     // Check if request wants ActivityPub content for profile
     const accept = request.headers.accept || '';
     const wantsAP = accept.includes('activity+json') || accept.includes('ld+json; profile="https://www.w3.org/ns/activitystreams"');
@@ -368,6 +377,7 @@ export function createServer(options = {}) {
         (gitEnabled && isGitRequest(request.url)) ||
         (activitypubEnabled && apPaths.some(p => request.url === p || request.url.startsWith(p + '?'))) ||
         isProfileAP ||
+        request.url.startsWith('/storage/') ||
         (mongoEnabled && (request.url === '/db' || request.url.startsWith('/db/'))) ||
         mashlibPaths.some(p => request.url === p || request.url.startsWith(p + '.'))) {
       return;