@bwog/bwog 0.0.0-stage → 0.1.1

package/.env.example

@@ -0,0 +1,15 @@
+NODE_ENV=production
+GOOGLE_OAUTH_CLIENT_ID=12345ABCDE.apps.googleusercontent.com
+GOOGLE_OAUTH_CLIENT_SECRET=12345ABCDE
+GOOGLE_OAUTH_AUTHORIZED_USER_ID=12345ABCDE
+SITE_DOMAIN=example.com
+SESSION_SECRET=12345ABCDE
+PUBLIC_PATH=/var/www/example
+DATABASE_TYPE=JSON
+DATABASE_FILE=/usr/share/bwog/blog.json
+AUTHOR_NAME=Alice Smith
+AUTHOR_EMAIL=author@example.com
+ENABLE_AP=false
+AP_HANDLE=author@example.com
+AP_USERNAME=author
+AP_PUBLIC_KEY_STRING="-----BEGIN PUBLIC KEY-----\nabc123\n-----END PUBLIC KEY-----"

package/COPYING

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Chase Patterson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,191 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center"><img src="images/logo.png" alt="bwog" style="width: 20em;" /></p>
+<p align="center">bwog is a toy static site generator for a tumblelog/microblog</p>
+
+## Architecture
+The blog generated is by-and-large a static HTML site. The other component is a small nodejs app which facilitates adding posts and regenerating the site.
+
+### HTTP Server (NGINX)
+
+This structure can be seen in the included example nginx site configuration (any static server and reverse proxy can be used).
+
+The provided site config will need to be edited (for your domain, certificate locations, and ActivityPub `Actor` handle), or otherwise integrated into your server configuration.
+
+This block attempts to find a file at the webroot matching the path in the requested URL:
+```
+root /var/www/example;
+index index.html;
+	
+location / {
+	try_files $uri $uri/ =404;
+}
+```
+
+This more-specific regex block is actually checked first. If the request matches any of these specific endpoints, it's forwarded to the express app running on port 3000. 
+```
+location ~ ^/(post|login|logout|oauth2/redirect/google) {
+	proxy_pass http://localhost:3000;
+	proxy_http_version 1.1;
+	proxy_set_header Upgrade $http_upgrade;
+	proxy_set_header Connection 'upgrade';
+	proxy_set_header Host $host;
+	proxy_cache_bypass $http_upgrade;
+}
+```
+
+#### ActivityPub
+
+This block uses the related map and only returns a resource if the correct WebFinger `acct:` URI is requested.
+
+If you already have a WebFinger system set up on the domain, the data from the generated `{PUBLIC_PATH}/ap/webfinger.json` should be served there.
+
+```
+location /.well-known/webfinger {
+	default_type "application/jrd+json";
+	try_files $webfinger_resource =404;
+}
+```
+```
+map $arg_resource $webfinger_resource {
+    "acct:username@example.com" /ap/webfinger.json;
+    "acct%3Ausername%40example.com" /ap/webfinger.json;
+}
+```
+
+The `/ap/actor` resource referenced from the WebFinger is served via a matching file at the relative webroot path.
+```
+location /ap {
+	types { } default_type "application/activity+json";
+	try_files $uri.json =404;
+}
+```
+
+The Outbox index and its pagination are served via the following directives:
+```
+location /ap/outbox {
+	types { } default_type "application/activity+json";
+	try_files $outbox =404;
+}
+```
+```
+map $arg_page $outbox {
+    "" /ap/outbox.json;
+    "~^(?<i>[0-9]+-[0-9]+)?" /ap/outbox_pages/$i.json;
+}
+```
+
+And Notes and their respective Create activities are served via these:
+```
+location /ap/notes {
+	types { } default_type "application/activity+json";
+	try_files $notes =404;
+}
+```
+```
+map $uri $note_id {
+    "~^/ap/notes/(?<id>.+)$" $id;
+}
+
+map $arg_activity $notes {
+    "true" /ap/creates/$note_id.json;
+    default /ap/notes/$note_id.json;
+}
+```
+
+## Dependencies
+Install dependencies with npm:
+```
+npm install
+```
+
+## Daemon
+The nodejs app can be run however you prefer to run daemons on your system. A systemd unit file is included at `bwog.service`.
+
+## Configuration
+The included `.env.example` can be copied to `.env` and the values replaced.
+
+The javascript oauth library Passport is used to authenticate via Google account. You must set up an oauth2 client on the Google Developer Console in the Google Auth Platform and copy the credentials here:
+```
+GOOGLE_OAUTH_CLIENT_ID=12345ABCDE
+GOOGLE_OAUTH_CLIENT_SECRET=12345ABCDE
+```
+The id of the user to whom you wish to allow post access:
+```
+GOOGLE_OAUTH_AUTHORIZED_USER_ID=12345ABCDE
+```
+A long random string to encrypt the session:
+```
+SESSION_SECRET=12345ABCDE
+```
+The path to your static files (where they should be generated):
+```
+PUBLIC_PATH=/var/www/example
+```
+The type of database: `JSON` or `SQLITE`
+```
+DATABASE_TYPE=JSON
+```
+The path to your source post JSON or SQLite (corresponding to `DATABASE_TYPE`). This will be updated, and used to generate the site.
+```
+DATABASE_FILE=/usr/share/bwog/blog.json
+```
+
+### Favicon
+Place an image to be used as a favicon, ActivityPub icon, and Atom feed icon at the server webroot (`.env` `PUBLIC_PATH`). A 400px square png works well.
+
+## Post data
+The source JSON has the following structure. Note the three types and following related properties. `id` is a base58 UUIDv4.
+```json
+[
+  {
+    "id": "123456789aAbBcCdDeEfFg",
+    "author": "John Blog",
+    "createdAt": "2025-05-01T16:58:00Z",
+    "type": "text",
+    "text": "Hello, world."
+  },
+  {
+    "id": "GhHijJkKlmMnNopPqQrRsS",
+    "author": "John Blog",
+    "createdAt": "2025-05-02T10:58:00Z",
+    "type": "song",
+    "text": "Listen to this song https://youtu.be/vyut3GyQtn0",
+    "artist": "Télépopmusik",
+    "title": "Breathe"
+  },
+  {
+    "id": "tTuUvVwWxXyYzZ12345678",
+    "author": "John Blog",
+    "createdAt": "2025-05-03T20:38:00Z",
+    "text": "A couple slappin' tunes:\nhttps://www.youtube.com/watch?v=i-SpGB6DtHw\nhttps://www.youtube.com/watch?v=mMWCQa-Gwv0",
+    "type": "playlist",
+    "tracks": [
+      {
+        "artist": "The One AM Radio",
+        "title": "An Old Photo Of Your New Lover"
+      },
+      {
+        "artist": "Kings of Convenience",
+        "title": "Love Is No Big Truth"
+      }
+    ]
+  }
+]
+```
+
+## Usage
+When the server is running, you can hit the `/login` endpoint to start the oauth flow. When authenticated, a form appears at the top of each page for posting.
+
+Conversely `/logout` invalidates your session.
+
+## CLI utility
+If you need to generate the entire site from the terminal, e.g. if you change a template, you can run it like this:
+```
+node scripts/generate_site.js -u https://example.com -t JSON -i blog.json -o /var/www/example -n 'John Smith' -e 'jsmith@example.com' -l -a jsmith@example.com -m jsmith -k public.pem
+```
+
+## Interfaces & Protocols
+A sitemap is generated at `/sitemap.xml`.
+
+An Atom feed of the most recent 20 posts is generated at `/feed.atom`.
+
+The ActivityPub protocol is implemented to the extent that an `Actor` is discoverable and all of the posts are accessible via the linked outbox.

package/app.js

@@ -0,0 +1,20 @@
+import express from 'express';
+import session from 'express-session';
+import passport from 'passport';
+import 'dotenv/config';
+
+import authRouter from './routes/auth.js';
+import editorRouter from './routes/editor.js';
+
+const app = express();
+app.use(session({
+    secret: process.env['SESSION_SECRET'],
+    resave: false,
+    saveUninitialized: false,
+}));
+app.use(passport.authenticate('session'));
+app.use(express.urlencoded({type: 'application/x-www-form-urlencoded'}));
+app.use('/', authRouter);
+app.use('/', editorRouter);
+
+export default app;

package/bwog.config.js

@@ -0,0 +1,5 @@
+import resolve from 'node:path';
+
+export default {
+    templates: resolve('./templates'),
+}

package/bwog.service

@@ -0,0 +1,12 @@
+[Unit]
+Description=bwog editor
+After=network.target
+StartLimitIntervalSec=0
+
+[Service]
+Type=simple
+Restart=always
+ExecStart=/usr/bin/node --env-file=/var/www/bwog/.env /var/www/bwog/app.js
+
+[Install]
+WantedBy=multi-user.target

package/cli.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+
+import { program } from 'commander';
+
+import app from './app.js';
+
+program
+    .description('bwog command line utility');
+
+program.command('build')
+    .description('build required files for deployment')
+    .action(() => {
+    });
+
+program.command('run')
+    .description('start web server listening for requests')
+    .option('-p, --port <number>', 'ActivityPub public key path, e.g. ./public.pem', '3000')
+    .action(({port}) => {
+        app.listen(port);
+        console.log('listening');
+    });
+
+program.parse();

package/cloudflare/Database.js

@@ -0,0 +1,105 @@
+import { DurableObject } from 'cloudflare:workers'
+
+class Database extends DurableObject {
+    constructor(ctx, env) {
+        super(ctx, env);
+
+        this.db = ctx.storage.sql;
+    }
+
+    initSchema(posts) {
+        this.db.exec(`CREATE TABLE posts (
+            id TEXT PRIMARY KEY,
+            author TEXT  NOT NULL,
+            created_at TEXT  NOT NULL,
+            content JSONB NOT NULL
+        );`);
+    }
+
+    importPosts(posts) {
+        posts.forEach(post => {
+            const content = {...post};
+            delete content.id;
+            delete content.author;
+            delete content.createdAt;
+            this.db.exec(
+                'INSERT INTO posts (id, author, created_at, content) VALUES (?, ?, ?, jsonb(?));',
+                post.id,
+                post.author,
+                post.createdAt,
+                JSON.stringify(content)
+            );
+        });
+    }
+
+    getAll() {
+        const rawPosts = this.db.exec(`
+            SELECT
+                id,
+                author,
+                created_at,
+                json(content) as content
+            FROM posts
+            ORDER BY created_at DESC;
+        `).toArray();
+
+        return rawPosts.map(post => ({
+            id: post.id,
+            author: post.author,
+            createdAt: post.created_at,
+            ...JSON.parse(post.content)
+        }));
+    }
+
+    getLastTwoMonthsAtLeast20() {
+        const rawPosts = this.db.exec(`
+            WITH latest_two_months AS (
+                SELECT DISTINCT strftime('%Y-%m', created_at) AS month
+                FROM posts
+                ORDER BY month DESC
+                LIMIT 2
+            ),
+            suitability AS (
+                SELECT *,
+                    CASE
+                        WHEN created_at IN latest_two_months THEN 1
+                        ELSE 0
+                    END AS in_latest_two_months,
+                    ROW_NUMBER() OVER (ORDER BY created_at DESC) AS recency
+                FROM posts
+            )
+            SELECT
+                id,
+                author,
+                created_at,
+                json(content) as content
+            FROM suitability
+            WHERE in_latest_two_months = 1
+               OR recency <= 20
+            ORDER BY created_at DESC;
+        `).toArray();
+
+        return rawPosts.map(post => ({
+            id: post.id,
+            author: post.author,
+            createdAt: post.created_at,
+            ...JSON.parse(post.content)
+        }));
+    }
+
+    createPost(post) {
+        const content = {...post};
+        delete content.id;
+        delete content.author;
+        delete content.createdAt;
+        this.db.exec(
+            'INSERT INTO posts (id, author, created_at, content) VALUES (?, ?, ?, jsonb(?));',
+            post.id,
+            post.author,
+            post.createdAt,
+            JSON.stringify(content)
+        );
+    }
+}
+
+export default Database;

package/cloudflare/worker.js

@@ -0,0 +1,104 @@
+import { Hono } from 'hono';
+import { jwt, sign } from 'hono/jwt';
+import { csrf } from 'hono/csrf';
+import { setCookie, deleteCookie } from 'hono/cookie';
+import { googleAuth } from '@hono/oauth-providers/google';
+
+import R2Store from '../stores/R2Store.js';
+import DurableObjectDatabase from '../databases/DurableObjectDatabase.js';
+import Controller from '../controller.js';
+import Generator from '../generator.js';
+
+const app = new Hono();
+
+app.use(csrf());
+
+app.use('/login', (c, next) => googleAuth({
+    client_id: c.env.GOOGLE_OAUTH_CLIENT_ID,
+    client_secret: c.env.GOOGLE_OAUTH_CLIENT_SECRET,
+    scope: ['email', 'profile'],
+})(c, next));
+
+app.get('/login', async c => {
+    const expirationSeconds = 60 * 60 * 24 * 7;
+    const user = c.get('user-google');
+
+    if (user.id !== c.env.GOOGLE_OAUTH_AUTHORIZED_USER_ID) {
+        deleteCookie(c, 'authToken');
+        deleteCookie(c, 'isAuthed');
+        return c.redirect('/');
+    }
+
+    const payload = {
+        sub: user,
+        exp: Math.floor(Date.now() / 1000) + expirationSeconds,
+    }
+
+    const jwtToken = await sign(payload, c.env.JWT_SECRET, 'HS256');
+
+    setCookie(c, 'authToken', jwtToken, {
+        path: '/',
+        secure: true,
+        httpOnly: true,
+        sameSite: 'Strict',
+        maxAge: expirationSeconds,
+    });
+    setCookie(c, 'isAuthed', true, {
+        path: '/',
+        secure: true,
+        httpOnly: false,
+        sameSite: 'Strict',
+        maxAge: expirationSeconds,
+    });
+
+    return c.redirect('/');
+});
+
+app.use('/post', (c, next) => jwt({
+    secret: c.env.JWT_SECRET,
+    alg: 'HS256',
+    cookie: 'authToken',
+})(c, next));
+
+app.post(['/post', '/generate'], async c => {
+    const user = c.get('jwtPayload').sub;
+    const stub = c.env.DATABASE.getByName('blog-posts');
+    const store = new R2Store(c.env.STORE);
+    const database = new DurableObjectDatabase(stub);
+    const controller = new Controller(store, database);
+
+    await controller.createPost(await c.req.parseBody(), user);
+
+    return c.redirect('/');
+});
+
+app.get('/setup', async c => {
+    const stub = c.env.DATABASE.getByName('blog-posts');
+    const store = new R2Store(c.env.STORE);
+    const database = new DurableObjectDatabase(stub);
+    const generator = new Generator(store, database);
+
+    const postsFile = await c.env.PRIVATE_BUCKET.get('posts.json');
+    const posts = await postsFile.json();
+
+    await database.initSchema();
+    await database.importPosts(posts);
+
+    await generator.generate(`https://${process.env['SITE_DOMAIN']}`, process.env['AUTHOR_NAME'], process.env['AUTHOR_EMAIL'], false);
+
+    return c.redirect('/');
+});
+
+app.get('/generate', async c => {
+    const stub = c.env.DATABASE.getByName('blog-posts');
+    const store = new R2Store(c.env.STORE);
+    const database = new DurableObjectDatabase(stub);
+    const generator = new Generator(store, database);
+
+    await generator.generate(`https://${process.env['SITE_DOMAIN']}`, process.env['AUTHOR_NAME'], process.env['AUTHOR_EMAIL'], false);
+
+    return c.redirect('/');
+});
+
+export { default as Database } from './Database.js';
+export default app;

package/config.js

@@ -0,0 +1,13 @@
+import { resolve } from 'node:path';
+
+let config = {};
+
+config = import('bwog.config')
+    .catch(async () => {
+        config = await import(resolve(process.cwd(), './bwog.config.js'));
+    })
+    .catch(() => {
+        throw new Error('Could not locate bwog config file at alias or working directory');
+    })
+
+export default config;

package/controller.js

@@ -0,0 +1,58 @@
+import {generate} from 'short-uuid';
+
+import Generator from './generator.js';
+
+class Controller {
+    constructor(store, database) {
+        this.store = store;
+        this.database = database;
+    }
+
+    async createPost(formData, user) {
+        if (!formData.text && !formData.tracks) {
+            return null;
+        }
+        let post = {
+            id: generate(),
+            author: user.name,
+            createdAt: (new Date()).toISOString().split('.')[0] + 'Z',
+            text: formData.text.replaceAll('\r\n', '\n'),
+        };
+        const trackStrings = formData.tracks.replaceAll('\r\n', '\n').split('\n');
+        const trackStringsFiltered = trackStrings.filter(track => track !== '');
+        const tracks = trackStringsFiltered.map(track => {
+            const tuple = track.split(' - ');
+            return {
+                artist: tuple[0],
+                title: tuple[1],
+            };
+        });
+        post.type = tracks.length > 0
+            ? (tracks.length > 1 ? 'playlist' : 'song')
+            : 'text';
+
+        switch (post.type) {
+            case 'playlist':
+                post.tracks = tracks;
+                break;
+            case 'song':
+                post = {...post, ...tracks[0]};
+                break;
+            case 'text':
+            default:
+                break;
+        }
+
+        this.database.createPost(post);
+
+        const generator = new Generator(this.store, this.database);
+        await generator.generatePartial(`https://${process.env['SITE_DOMAIN']}`, process.env['AUTHOR_NAME'], process.env['AUTHOR_EMAIL'], process.env['ENABLE_AP'] === 'true', post);
+
+        console.log(`user posted: ${user.name} <${user.email}>`);
+        console.log(post);
+
+        return post;
+    }
+}
+
+export default Controller;

package/databases/DurableObjectDatabase.js

@@ -0,0 +1,30 @@
+class DurableObjectDatabase {
+    constructor(file) {
+        this.file = file;
+    }
+
+    async connect() {
+    }
+
+    async initSchema() {
+        return this.file.initSchema();
+    }
+
+    async importPosts(posts) {
+        return this.file.importPosts(posts);
+    }
+
+    async getAll() {
+        return this.file.getAll();
+    }
+
+    async getLastTwoMonthsAtLeast20() {
+        return this.file.getLastTwoMonthsAtLeast20();
+    }
+
+    async createPost(post) {
+        return this.file.createPost(post);
+    }
+}
+
+export default DurableObjectDatabase;

package/databases/JsonDatabase.js

@@ -0,0 +1,38 @@
+import fs from 'fs';
+import beautify from 'js-beautify';
+
+class JsonDatabase {
+    constructor(file) {
+        this.file = file;
+    }
+
+    async connect() {
+        const { default: posts } = await import(this.file, {with: {type: 'json'}});
+        this.posts = posts;
+        this.posts.sort((a, b) => a.createdAt > b.createdAt ? -1 : (a.createdAt < b.createdAt ? 1 : 0));
+    }
+
+    async getAll() {
+        return this.posts;
+    }
+
+    async getLastTwoMonthsAtLeast20() {
+        return this.posts;
+    }
+
+    async createPost(post) {
+        this.posts.push(post);
+
+        try {
+            const json = beautify.js(
+                JSON.stringify(this.posts),
+                {end_with_newline: true},
+            );
+            fs.writeFileSync(this.file, json);
+        } catch (err) {
+            throw (`Failed to write file: ${this.file}`);
+        }
+    }
+}
+
+export default JsonDatabase;