@o-a/cms-agent 0.1.0

package/dist/services/token-auth.js

@@ -0,0 +1,64 @@
+import { createHash, timingSafeEqual } from 'node:crypto';
+// The first domain error in this codebase's established XxxError+
+// reason convention that has to cross the Fastify HTTP boundary -
+// every prior one throws pre-HTTP (at boot) or predates Phase 2
+// entirely. statusCode is set explicitly in the constructor so the
+// existing global error handler (server.ts, which branches on
+// error.statusCode) passes these through with their real message
+// intact, never sanitising them as a generic 500 - confirmed
+// empirically that a preHandler-thrown error with .statusCode set
+// reaches that same handler correctly.
+export class AuthError extends Error {
+    reason;
+    statusCode;
+    constructor(reason, message) {
+        super(message);
+        this.name = 'AuthError';
+        this.reason = reason;
+        this.statusCode = reason === 'missing-scope' ? 403 : 401;
+    }
+}
+const BEARER_PREFIX = 'Bearer ';
+function hashToken(token) {
+    return createHash('sha256').update(token).digest();
+}
+// Never compare token digests (or hex strings) with === or
+// Buffer.equals() - neither is guaranteed constant-time. Only
+// timingSafeEqual, which is why both sides must first be reduced to
+// a fixed-length digest: it throws on mismatched buffer lengths, and
+// a raw incoming token is never the same length as another token in
+// general (confirmed empirically before this was written).
+export function verifyToken(tokens, presentedToken) {
+    const presentedDigest = hashToken(presentedToken);
+    for (const entry of tokens) {
+        const storedDigest = Buffer.from(entry.hash, 'hex');
+        if (timingSafeEqual(presentedDigest, storedDigest)) {
+            return entry.scopes;
+        }
+    }
+    return null;
+}
+// Applied as a per-route preHandler option
+// (fastify.get(path, { preHandler: requireScope(tokens, 'content') }, handler)),
+// not a whole-file addHook: a single route-group file may eventually
+// mix scopes (e.g. a content-scoped GET and a media-scoped POST in
+// the same file), so the check is granular to the route, not the
+// file. Each route-group file still registers plainly, never wrapped
+// in fastify-plugin's fp(), preserving the per-plugin encapsulation
+// this design depends on.
+export function requireScope(tokens, scope) {
+    return async function scopeGuard(request) {
+        const header = request.headers.authorization;
+        if (!header || !header.startsWith(BEARER_PREFIX)) {
+            throw new AuthError('missing-token', 'Missing or malformed Authorization header');
+        }
+        const presentedToken = header.slice(BEARER_PREFIX.length);
+        const scopes = verifyToken(tokens, presentedToken);
+        if (scopes === null) {
+            throw new AuthError('invalid-token', 'The presented token does not match any configured token');
+        }
+        if (!scopes.includes(scope)) {
+            throw new AuthError('missing-scope', `This route requires the "${scope}" scope`);
+        }
+    };
+}

package/dist/services/urls.d.ts

@@ -0,0 +1,2 @@
+export declare function urlToPagePath(url: string): string;
+export declare function pagePathToUrl(relativePagePath: string): string;

package/dist/services/urls.js

@@ -0,0 +1,20 @@
+// Pure, filesystem-free mapping between a public URL and a page's path
+// relative to pagesRoot. A page with children is a file (about.json)
+// sitting alongside a same-named sibling directory (about/) holding
+// descendants, so this mapping never needs to know whether a given
+// page currently has children - unlike an about/index.json convention,
+// which would make resolution filesystem-dependent.
+export function urlToPagePath(url) {
+    const trimmed = url.replace(/^\/+/, '').replace(/\/+$/, '');
+    if (trimmed === '') {
+        return 'index.json';
+    }
+    return `${trimmed}.json`;
+}
+export function pagePathToUrl(relativePagePath) {
+    const withoutExtension = relativePagePath.replace(/\.json$/, '');
+    if (withoutExtension === 'index') {
+        return '/';
+    }
+    return `/${withoutExtension}`;
+}

package/dist/services/validation.d.ts

@@ -0,0 +1,24 @@
+export interface ValidationError {
+    path: string;
+    message: string;
+    keyword: string;
+}
+export interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+}
+export interface ThemeSchemas {
+    sections: Record<string, object>;
+    blocks: Record<string, object>;
+    acceptsBlocks: {
+        sections: Record<string, boolean>;
+        blocks: Record<string, boolean>;
+    };
+}
+export declare function requiredFieldsHaveValidDefaults(schema: object): boolean;
+export declare function validateInstance(instance: unknown, kind: 'section' | 'block', themeSchemas: ThemeSchemas): ValidationResult;
+export declare function validatePage(page: unknown, themeSchemas: ThemeSchemas): ValidationResult;
+export declare function validatePost(post: unknown, themeSchemas: ThemeSchemas): ValidationResult;
+export declare function validateMenu(menu: unknown): ValidationResult;
+export declare function validateRedirects(redirects: unknown): ValidationResult;
+export declare function validateContent(relativePath: string, content: unknown, themeSchemas: ThemeSchemas): ValidationResult;

package/dist/services/validation.js

@@ -0,0 +1,158 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { Ajv } from 'ajv';
+// strict: false because theme schema.json files are authored by theme
+// authors, not agent code, and are validated the same lenient way
+// everywhere (see theme-schemas.ts).
+const ajv = new Ajv({ allErrors: true, strict: false });
+const schemasDir = join(import.meta.dirname, '..', 'schemas');
+function readSchema(filename) {
+    return JSON.parse(readFileSync(join(schemasDir, filename), 'utf-8'));
+}
+const instanceSchema = readSchema('instance.schema.json');
+ajv.addSchema(instanceSchema);
+const validatePageEnvelope = ajv.compile(readSchema('page.schema.json'));
+const validatePostEnvelope = ajv.compile(readSchema('post.schema.json'));
+const validateMenuEnvelope = ajv.compile(readSchema('menu.schema.json'));
+const validateRedirectsEnvelope = ajv.compile(readSchema('redirects.schema.json'));
+const validateInstanceEnvelope = ajv.compile(instanceSchema);
+function normaliseErrors(errors) {
+    if (!errors) {
+        return [];
+    }
+    return errors.map((error) => {
+        let path = error.instancePath;
+        if (error.keyword === 'required') {
+            const { missingProperty } = error.params;
+            path = `${error.instancePath}/${missingProperty}`;
+        }
+        else if (error.keyword === 'additionalProperties') {
+            const { additionalProperty } = error.params;
+            path = `${error.instancePath}/${additionalProperty}`;
+        }
+        return { path, message: error.message ?? '', keyword: error.keyword };
+    });
+}
+function runValidator(validate, data) {
+    const valid = validate(data);
+    return { valid: Boolean(valid), errors: normaliseErrors(validate.errors) };
+}
+function prefixErrors(errors, prefix) {
+    return errors.map((error) => ({ ...error, path: `${prefix}${error.path}` }));
+}
+// The theme-authored schema JSON is passed through verbatim end to end
+// (see theme-schemas.ts), so an optional allowedBlocks array rides
+// through the whole pipeline for free, exactly like the "title" keyword
+// already does - never a real Ajv keyword, just a plain top-level
+// annotation read directly off the object. Absent/malformed means
+// unrestricted, matching every theme file written before this existed.
+function allowedBlockTypesOf(schema) {
+    const value = schema?.allowedBlocks;
+    return Array.isArray(value) && value.every((entry) => typeof entry === 'string') ? value : undefined;
+}
+// A theme author's own settings schema must declare a "default" for
+// every property it lists as required, and that default must itself
+// satisfy the property's own sub-schema - a bare "default": "" against
+// a minLength: 1 field would technically have a default but still
+// leave a pre-filled instance invalid, defeating the reason this
+// exists (see theme-schemas.ts, which skips a type failing this check
+// exactly like it already skips a malformed {% schema %} block).
+export function requiredFieldsHaveValidDefaults(schema) {
+    const { required, properties } = schema;
+    if (!Array.isArray(required)) {
+        return true;
+    }
+    const propertyMap = (properties && typeof properties === 'object' ? properties : {});
+    return required.every((name) => {
+        if (typeof name !== 'string') {
+            return false;
+        }
+        const propertySchema = propertyMap[name];
+        if (typeof propertySchema !== 'object' || propertySchema === null || !('default' in propertySchema)) {
+            return false;
+        }
+        return ajv.validate(propertySchema, propertySchema.default) === true;
+    });
+}
+export function validateInstance(instance, kind, themeSchemas) {
+    const envelopeResult = runValidator(validateInstanceEnvelope, instance);
+    if (!envelopeResult.valid) {
+        return envelopeResult;
+    }
+    const typed = instance;
+    const typeSchemas = kind === 'section' ? themeSchemas.sections : themeSchemas.blocks;
+    const typeSchema = typeSchemas[typed.type];
+    const errors = [];
+    if (!typeSchema) {
+        errors.push({
+            path: '/type',
+            message: `Unknown ${kind} type "${typed.type}"`,
+            keyword: 'unknownType',
+        });
+    }
+    else {
+        const settingsValidate = ajv.compile(typeSchema);
+        const settingsResult = runValidator(settingsValidate, typed.settings);
+        errors.push(...prefixErrors(settingsResult.errors, '/settings'));
+    }
+    if (typed.blocks) {
+        const allowedBlocks = allowedBlockTypesOf(typeSchema);
+        typed.blocks.forEach((block, index) => {
+            const blockType = block?.type;
+            if (allowedBlocks && typeof blockType === 'string' && !allowedBlocks.includes(blockType)) {
+                errors.push({
+                    path: `/blocks/${index}/type`,
+                    message: `Block type "${blockType}" is not allowed here`,
+                    keyword: 'disallowedBlockType',
+                });
+            }
+            const blockResult = validateInstance(block, 'block', themeSchemas);
+            errors.push(...prefixErrors(blockResult.errors, `/blocks/${index}`));
+        });
+    }
+    return { valid: errors.length === 0, errors };
+}
+// Shared by validatePage and validatePost: both envelopes require an
+// identical sections/blocks recursion once their own envelope-level
+// shape is confirmed valid - genuinely load-bearing for two real
+// content types now, not a speculative abstraction.
+function validateSectionedContent(envelopeValidate, content, themeSchemas) {
+    const envelopeResult = runValidator(envelopeValidate, content);
+    if (!envelopeResult.valid) {
+        return envelopeResult;
+    }
+    const typed = content;
+    const errors = [];
+    typed.sections.forEach((section, index) => {
+        const sectionResult = validateInstance(section, 'section', themeSchemas);
+        errors.push(...prefixErrors(sectionResult.errors, `/sections/${index}`));
+    });
+    return { valid: errors.length === 0, errors };
+}
+export function validatePage(page, themeSchemas) {
+    return validateSectionedContent(validatePageEnvelope, page, themeSchemas);
+}
+export function validatePost(post, themeSchemas) {
+    return validateSectionedContent(validatePostEnvelope, post, themeSchemas);
+}
+export function validateMenu(menu) {
+    return runValidator(validateMenuEnvelope, menu);
+}
+// Never routed through validateContent's dispatcher below: redirects.json
+// lives at the site root, not under content/, so it never has a
+// content/-relative path for that dispatcher to match against.
+export function validateRedirects(redirects) {
+    return runValidator(validateRedirectsEnvelope, redirects);
+}
+// Dispatches on the relative path's prefix, not an in-file `type`
+// field: a menu has no `type` field at all, and the correct schema to
+// parse against must be known before the content is even validated.
+export function validateContent(relativePath, content, themeSchemas) {
+    if (relativePath.startsWith('menus/')) {
+        return validateMenu(content);
+    }
+    if (relativePath.startsWith('posts/')) {
+        return validatePost(content, themeSchemas);
+    }
+    return validatePage(content, themeSchemas);
+}

package/dist/services/write-queue.d.ts

@@ -0,0 +1 @@
+export declare function enqueue<T>(job: () => Promise<T>): Promise<T>;

package/dist/services/write-queue.js

@@ -0,0 +1,14 @@
+// The single in-process write queue: all disk and git mutations go
+// through enqueue(), one job at a time (constraint 6). Ordering only -
+// no domain knowledge of what "clean" means for a failed job. That is
+// each job's own responsibility (see drafts.ts, publish.ts).
+//
+// In-memory only, does not survive restart: the API only reports
+// success after a write (and commit, where applicable) completes, so an
+// in-flight request during a crash simply fails and the caller retries.
+let tail = Promise.resolve();
+export function enqueue(job) {
+    const result = tail.then(job, job);
+    tail = result.then(() => undefined, () => undefined);
+    return result;
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@o-a/cms-agent",
+  "version": "0.1.0",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Self-hosted, git-backed CMS agent, distributed as a compiled npm package.",
+  "license": "SEE LICENSE IN LICENSE",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "create-site": "dist/create-site/cli.js",
+    "mint-token": "dist/create-site/mint-token-cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.6.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "lint": "eslint .",
+    "test": "node --experimental-strip-types --test",
+    "test:packaging": "node --experimental-strip-types --test e2e/create-site-packaging.check.ts",
+    "build": "tsc -p tsconfig.build.json && rm -rf dist/schemas dist/create-site/template && cp -r src/schemas/. dist/schemas/ && cp -r src/create-site/template/. dist/create-site/template/",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.5",
+    "@types/localtunnel": "^2.0.4",
+    "@types/node": "^22.20.1",
+    "eslint": "^9.39.5",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.65.0"
+  },
+  "dependencies": {
+    "@fastify/multipart": "^10.1.0",
+    "@fastify/rate-limit": "^11.1.0",
+    "ajv": "^8.20.0",
+    "fastify": "^5.10.0",
+    "liquidjs": "10.27.2",
+    "localtunnel": "^2.0.2"
+  }
+}