@ofidj/generator-fidj 1.0.0 → 1.0.1

package/generators/app/templates/typescript/scripts/build.mjs

@@ -0,0 +1,46 @@
+import { build } from "esbuild";
+import { cp, mkdir, rm, readFile, writeFile, readdir } from "node:fs/promises";
+const config = JSON.parse(await readFile("app.config.json", "utf8"));
+const contentApp = typeof config.content === "string";
+await rm("dist", { recursive: true, force: true });
+await mkdir("dist/public", { recursive: true });
+await cp("public", "dist/public", { recursive: true });
+await Promise.all([
+  build({
+    entryPoints: [contentApp ? "src/content.ts" : "src/main.ts"],
+    bundle: true,
+    platform: "browser",
+    target: "es2022",
+    outfile: "dist/public/main.js",
+    sourcemap: true,
+  }),
+  build({
+    entryPoints: ["server/index.ts"],
+    bundle: true,
+    packages: "external",
+    platform: "node",
+    target: "node22",
+    format: "cjs",
+    outfile: "dist/server.cjs",
+  }),
+]);
+if (contentApp) {
+  const { renderContent } = await import("./render-content.mjs");
+  await writeFile("dist/public/index.html", renderContent(config));
+  await rm("www", { recursive: true, force: true });
+  await cp("dist/public", "www", { recursive: true });
+  if (config.domain) await writeFile("www/CNAME", config.domain + "\n");
+}
+await cp("dist/public/index.html", "dist/public/app.html");
+
+const moduleFiles = {};
+async function collect(directory, relative = "") {
+  for (const item of await readdir(directory, { withFileTypes: true })) {
+    const name = relative + item.name;
+    if (item.isDirectory())
+      await collect(directory + "/" + item.name, name + "/");
+    else moduleFiles["/" + name] = name;
+  }
+}
+await collect("dist/public");
+await writeFile("dist/public-files.json", JSON.stringify(moduleFiles));

package/generators/app/templates/typescript/scripts/privacy-check.mjs

@@ -0,0 +1,21 @@
+import {createHmac, randomUUID} from 'node:crypto';
+
+try {
+  const key = process.env.FIDJ_PRIVACY_ADAPTER_KEY;
+  const appId = process.env.FIDJ_APP_ID;
+  if (!appId || !key || key.length < 32) throw new Error('Set FIDJ_APP_ID and a private FIDJ_PRIVACY_ADAPTER_KEY of at least 32 characters in .env.');
+  const url = new URL(process.env.FIDJ_APP_URL || `http://127.0.0.1:${process.env.PORT || 8200}`);
+  if (url.username || url.password || url.search || url.hash || (url.protocol !== 'https:' && !(url.protocol === 'http:' && ['localhost', '127.0.0.1'].includes(url.hostname)))) throw new Error('Use a trusted HTTPS app URL, or loopback HTTP for development.');
+  url.pathname = url.pathname.replace(/\/$/, '') + '/fidj/privacy';
+  const timestamp = String(Date.now());
+  const data = {appId, subject: 'readiness-check', operation: 'check', requestId: randomUUID()};
+  const text = JSON.stringify(data);
+  const response = await fetch(url, {method: 'POST', headers: {'Content-Type': 'application/json', 'x-fidj-timestamp': timestamp, 'x-fidj-signature': createHmac('sha256', key).update(timestamp + '.' + text).digest('hex')}, body: text, signal: AbortSignal.timeout(5000), redirect: 'error'});
+  if (!response.ok) throw new Error('The app-data handler could not be verified. Check the URL, shared secret and server.');
+  const result = await response.json();
+  if (result.requestId !== data.requestId || result.status !== 'completed' || result.storage !== 'ready' || !['export', 'erase'].every(capability => result.capabilities?.includes(capability))) throw new Error('The handler did not confirm both operations and writable storage.');
+  console.log('Ready: app-data export, erasure and writable storage verified. No user data was created or erased.');
+} catch (error) {
+  console.error(error.message || 'The readiness check failed.');
+  process.exitCode = 1;
+}

package/generators/app/templates/typescript/scripts/render-content.mjs

@@ -0,0 +1,14 @@
+const escape = (value) =>
+  String(value ?? "").replace(
+    /[&<>"']/g,
+    (char) =>
+      ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[
+        char
+      ],
+  );
+export function renderContent(config) {
+  // HTML is supplied by the developer at generation time, never by an app visitor.
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><meta name="referrer" content="no-referrer"><title>${escape(config.title)}</title><link rel="icon" href="./fidj-logo.png"><link rel="stylesheet" href="./main.css"></head><body>
+  <header class="topbar"><a class="brand" href="#/content">${escape(config.title)}</a><a class="fidj-brand" href="${escape(config.moduleEntry || config.dashboardUrl + "/#/my")}"><img src="./fidj-logo.png" alt="Fidj">My privacy ↗</a></header>
+  <main><template id="public-content"><section class="card public-content"><h1>${escape(config.welcome)}</h1><div>${config.content}</div></section></template><div id="app" aria-live="polite"></div><footer>Built with Fidj · Your choices belong to this app.</footer></main><script type="module" src="./main.js"></script></body></html>`;
+}

package/generators/app/templates/typescript/server/data-store.ts

@@ -0,0 +1,123 @@
+import {
+  mkdir,
+  readFile,
+  open,
+  rename,
+  readdir,
+  unlink,
+} from "node:fs/promises";
+import { join } from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+
+export interface Note {
+  id: string;
+  title: string;
+  body: string;
+  createdAt: string;
+}
+interface State {
+  notes: Record<string, Note[]>;
+  receipts: Record<string, { subjectHash: string; completedAt: string }>;
+}
+
+// One writer process per directory. Replace this adapter with your database for multi-instance hosting.
+export class DataStore {
+  private queue: Promise<unknown> = Promise.resolve();
+  constructor(
+    private directory: string,
+    private appId = "",
+  ) {}
+  private async state(): Promise<State> {
+    try {
+      return JSON.parse(
+        await readFile(join(this.directory, "data.json"), "utf8"),
+      );
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT")
+        return { notes: {}, receipts: {} };
+      throw error;
+    }
+  }
+  private transact<T>(task: (state: State) => T | Promise<T>): Promise<T> {
+    const operation = this.queue.then(async () => {
+      await mkdir(this.directory, { recursive: true, mode: 0o700 });
+      // Interrupted writes must not leave a second copy of erased data behind.
+      for (const name of await readdir(this.directory)) {
+        if (/^[a-f0-9-]{36}\.tmp$/.test(name))
+          await unlink(join(this.directory, name));
+      }
+      const state = await this.state();
+      for (const [id, receipt] of Object.entries(state.receipts)) {
+        if (Date.parse(receipt.completedAt) < Date.now() - 30 * 86400000)
+          delete state.receipts[id];
+      }
+      const result = await task(state);
+      await mkdir(this.directory, { recursive: true, mode: 0o700 });
+      const temporary = join(this.directory, randomUUID() + ".tmp");
+      try {
+        const file = await open(temporary, "wx", 0o600);
+        try {
+          await file.writeFile(JSON.stringify(state));
+          await file.sync();
+        } finally {
+          await file.close();
+        }
+        await rename(temporary, join(this.directory, "data.json"));
+      } finally {
+        await unlink(temporary).catch((error) => {
+          if (error.code !== "ENOENT") throw error;
+        });
+      }
+      const directory = await open(this.directory, "r");
+      try {
+        await directory.sync();
+      } finally {
+        await directory.close();
+      }
+      return result;
+    });
+    this.queue = operation.catch(() => {});
+    return operation;
+  }
+  async check() {
+    await this.transact(() => undefined);
+    return {storage: "ready", capabilities: ["export", "erase"]};
+  }
+  async notes(subject: string): Promise<Note[]> {
+    await this.queue;
+    return (await this.state()).notes[this.key(subject)] || [];
+  }
+  add(subject: string, note: Note, authorize: () => Promise<unknown>) {
+    return this.transact(async (state) => {
+      await authorize();
+      const key = this.key(subject);
+      const notes = state.notes[key] || [];
+      if (notes.length >= 100) throw new Error("Note limit reached.");
+      state.notes[key] = [...notes, note];
+    });
+  }
+  erase(subject: string, requestId: string) {
+    return this.transact((state) => {
+      const subjectHash = this.key(subject);
+      const existing = state.receipts[requestId];
+      if (existing && existing.subjectHash !== subjectHash)
+        throw new Error("Receipt identity mismatch.");
+      // Re-delivery of a completed request must not erase data from a later membership.
+      if (existing)
+        return {
+          requestId,
+          status: "completed",
+          completedAt: existing.completedAt,
+        };
+      delete state.notes[subjectHash];
+      const completedAt = new Date().toISOString();
+      state.receipts[requestId] = { subjectHash, completedAt };
+      return { requestId, status: "completed", completedAt };
+    });
+  }
+  private key(subject: string) {
+    return createHash("sha256")
+      .update(this.appId + ":" + subject)
+      .digest("hex");
+  }
+}

package/generators/app/templates/typescript/server/index.ts

@@ -0,0 +1,329 @@
+import { createServer, IncomingMessage, ServerResponse } from "node:http";
+import { readFile } from "node:fs/promises";
+import { join, extname } from "node:path";
+import { DataStore } from "./data-store";
+import { verifyPrivacyRequest } from "./privacy-adapter";
+export { DataStore } from "./data-store";
+import { verifyAppSession, SessionVerificationError } from "@ofidj/node";
+
+export interface Settings {
+  appId: string;
+  apiEndpoint: string;
+  dashboardUrl: string;
+  title: string;
+  localDemo: boolean;
+}
+class HttpError extends Error {
+  constructor(
+    public status: number,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+async function body(req: IncomingMessage): Promise<any> {
+  let value = "";
+  for await (const chunk of req) {
+    value += chunk;
+    if (Buffer.byteLength(value) > 16384)
+      throw new HttpError(413, "Request too large.");
+  }
+  try {
+    return JSON.parse(value || "{}");
+  } catch {
+    throw new HttpError(400, "Invalid JSON.");
+  }
+}
+function json(res: ServerResponse, status: number, value: unknown) {
+  res.writeHead(status, {
+    "Content-Type": "application/json",
+    "Cache-Control": "no-store",
+    "X-Content-Type-Options": "nosniff",
+  });
+  res.end(JSON.stringify(value));
+}
+
+export function createApp(
+  settings: Settings,
+  options: { dataDir?: string; adapterKey?: string; store?: DataStore } = {},
+) {
+  const store =
+    options.store ||
+    new DataStore(
+      options.dataDir || join(process.cwd(), ".fidj-data"),
+      settings.appId,
+    );
+  const upstream = async (
+    token: string,
+    suffix: string,
+    method = "GET",
+    data?: unknown,
+  ) => {
+    let response: Response;
+    try {
+      response = await fetch(
+        `${settings.apiEndpoint}/me/apps/${encodeURIComponent(settings.appId)}${suffix}`,
+        {
+          method,
+          headers: {
+            Authorization: `Bearer ${token}`,
+            "Content-Type": "application/json",
+          },
+          body: data === undefined ? undefined : JSON.stringify(data),
+          signal: AbortSignal.timeout(5000),
+          redirect: "error",
+        },
+      );
+    } catch {
+      throw new HttpError(503, "Fidj is unavailable. Please retry.");
+    }
+    const result = await response.json().catch(() => ({}));
+    if (!response.ok)
+      throw new HttpError(
+        response.status,
+        result.status || "Fidj could not complete this action.",
+      );
+    return { status: response.status, data: result };
+  };
+  return createServer(async (req, res) => {
+    try {
+      const pathname = new URL(req.url || "/", "http://localhost").pathname;
+      if (pathname === "/fidj/privacy" && req.method === "POST") {
+        const input = await body(req);
+        if (
+          !verifyPrivacyRequest(
+            options.adapterKey,
+            String(req.headers["x-fidj-timestamp"] || ""),
+            String(req.headers["x-fidj-signature"] || ""),
+            input,
+          )
+        )
+          throw new HttpError(401, "Invalid privacy request.");
+        if (
+          input.appId !== settings.appId ||
+          typeof input.subject !== "string" ||
+          !input.subject ||
+          input.subject.length > 200 ||
+          typeof input.requestId !== "string" ||
+          !/^[a-zA-Z0-9-]{1,100}$/.test(input.requestId)
+        )
+          throw new HttpError(400, "Invalid privacy scope.");
+        if (input.operation === "check") return json(res, 200, {requestId: input.requestId, status: "completed", ...await store.check()});
+        if (input.operation === "export")
+          return json(res, 200, {
+            requestId: input.requestId,
+            status: "completed",
+            data: { notes: await store.notes(input.subject) },
+            coverage: "Notes stored by this app",
+          });
+        if (input.operation === "erase")
+          return json(
+            res,
+            200,
+            await store.erase(input.subject, input.requestId),
+          );
+        throw new HttpError(400, "Unsupported privacy operation.");
+      }
+      if (pathname === "/api/config" && req.method === "GET")
+        return json(res, 200, settings);
+      if (pathname === "/api/health" && req.method === "GET")
+        return json(res, 200, { status: "ready" });
+      if (pathname.startsWith("/api/")) {
+        const authorization = req.headers.authorization || "";
+        if (!authorization.startsWith("Bearer "))
+          throw new HttpError(401, "Sign in to continue.");
+        const token = authorization.slice(7);
+        const session = await verifyAppSession(token, settings);
+        if (pathname === "/api/session" && req.method === "GET")
+          return json(res, 200, session);
+        if (pathname === "/api/notes" && req.method === "GET")
+          return json(res, 200, { notes: await store.notes(session.subject) });
+        if (pathname === "/api/notes" && req.method === "POST") {
+          if (!session.roles.some((role) => ["Owner", "Editor"].includes(role)))
+            throw new HttpError(
+              403,
+              "An Editor or Owner role is required to save a note.",
+            );
+          const input = await body(req);
+          if (
+            typeof input.title !== "string" ||
+            !input.title.trim() ||
+            input.title.length > 120 ||
+            typeof input.body !== "string" ||
+            input.body.length > 5000
+          )
+            throw new HttpError(
+              400,
+              "Add a title (up to 120 characters) and a note (up to 5,000 characters).",
+            );
+          const current = await store.notes(session.subject);
+          if (current.length >= 100)
+            throw new HttpError(
+              409,
+              "This starter supports 100 notes per person.",
+            );
+          const note = {
+            id: crypto.randomUUID(),
+            title: input.title.trim(),
+            body: input.body,
+            createdAt: new Date().toISOString(),
+          };
+          await store.add(session.subject, note, () =>
+            verifyAppSession(token, settings),
+          );
+          return json(res, 201, { note });
+        }
+        if (pathname === "/api/privacy" && req.method === "GET") {
+          const [consent, history] = await Promise.all([
+            upstream(token, "/consents"),
+            upstream(token, "/consents/history"),
+          ]);
+          return json(res, 200, {
+            consent: consent.data,
+            history: history.data.history,
+          });
+        }
+        if (pathname === "/api/privacy" && req.method === "PUT") {
+          const input = await body(req);
+          const data: Record<string, unknown> = { source: "profile" };
+          for (const purpose of [
+            "terms",
+            "analytics",
+            "communications",
+            "optionalData",
+          ])
+            if (input[purpose] !== undefined) data[purpose] = input[purpose];
+          if (input.terms === true) data.termsVersion = "starter-demo-1";
+          const result = await upstream(token, "/consents", "PUT", data);
+          return json(res, result.status, result.data);
+        }
+        if (pathname === "/api/privacy/export" && req.method === "GET") {
+          const identity = await upstream(token, "/export");
+          return json(res, 200, {
+            exportedAt: new Date().toISOString(),
+            fidj: identity.data,
+            app: identity.data.applicationData || {
+              notes: await store.notes(session.subject),
+            },
+            coverage:
+              "Fidj records for this membership plus this app’s persisted notes. No other apps or independent external systems.",
+          });
+        }
+        if (pathname === "/api/privacy/leave" && req.method === "DELETE") {
+          const input = await body(req);
+          if (input.confirm !== settings.appId)
+            throw new HttpError(400, "Confirm this app before leaving.");
+          const connection = await upstream(token, "/consents");
+          if (!connection.data.appDataConnected)
+            throw new HttpError(
+              409,
+              "The app owner must connect the data-erasure handler before departure can include your notes.",
+            );
+          const result = await upstream(token, "", "DELETE", {
+            confirm: settings.appId,
+          });
+          return json(res, result.status, {
+            ...result.data,
+            appNotes: result.data.appData || "not_connected",
+          });
+        }
+        throw new HttpError(404, "Unknown operation.");
+      }
+      if (req.method !== "GET" && req.method !== "HEAD")
+        throw new HttpError(405, "Method not allowed.");
+      const files: Record<string, [string, string]> = {
+        "/": ["index.html", "text/html"],
+        "/index.html": ["index.html", "text/html"],
+        "/app": ["app.html", "text/html"],
+        "/hero.gif": ["hero.gif", "image/gif"],
+        "/main.js": ["main.js", "text/javascript"],
+        "/main.css": ["main.css", "text/css"],
+        "/fidj-logo.png": ["fidj-logo.png", "image/png"],
+      };
+      if (!files[pathname] && pathname.startsWith("/module/")) {
+        const manifest = JSON.parse(
+          await readFile(join(__dirname, "public-files.json"), "utf8"),
+        );
+        const asset =
+          manifest[pathname] ||
+          (pathname.endsWith("/")
+            ? manifest[pathname + "index.html"]
+            : undefined);
+        const types: Record<string, string> = {
+          ".html": "text/html",
+          ".js": "text/javascript",
+          ".css": "text/css",
+          ".json": "application/json",
+          ".png": "image/png",
+          ".svg": "image/svg+xml",
+          ".gif": "image/gif",
+          ".ico": "image/x-icon",
+          ".woff": "font/woff",
+          ".woff2": "font/woff2",
+        };
+        if (typeof asset === "string")
+          files[pathname] = [
+            asset,
+            types[extname(asset)] || "application/octet-stream",
+          ];
+      }
+      const file = files[pathname];
+      if (!file) throw new HttpError(404, "Not found.");
+      const content = await readFile(join(__dirname, "public", file[0]));
+      const apiOrigin = new URL(settings.apiEndpoint).origin;
+      res.writeHead(200, {
+        "Content-Type": file[1],
+        "X-Content-Type-Options": "nosniff",
+        "Referrer-Policy": "no-referrer",
+        "Content-Security-Policy": `default-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' https:; connect-src 'self' ${apiOrigin}; object-src 'none'; base-uri 'none'; frame-ancestors 'none'`,
+      });
+      res.end(req.method === "HEAD" ? undefined : content);
+    } catch (error) {
+      const status =
+        error instanceof HttpError || error instanceof SessionVerificationError
+          ? error.status
+          : 500;
+      json(res, status, {
+        message:
+          status === 500
+            ? "The app could not complete this action."
+            : (error as Error).message,
+      });
+    }
+  });
+}
+
+if (require.main === module) {
+  const appId = process.env.FIDJ_APP_ID;
+  if (!appId || !process.env.FIDJ_API_ENDPOINT)
+    throw new Error("Set FIDJ_APP_ID and FIDJ_API_ENDPOINT in .env.");
+  const apiEndpoint = process.env.FIDJ_API_ENDPOINT.replace(/\/$/, "");
+  const api = new URL(apiEndpoint);
+  if (
+    !["https:", "http:"].includes(api.protocol) ||
+    api.username ||
+    api.password ||
+    api.search ||
+    api.hash
+  )
+    throw new Error("Invalid Fidj API URL.");
+  const port = Number(process.env.PORT || 8200);
+  const host = process.env.HOST || "127.0.0.1";
+  const settings = {
+    appId,
+    apiEndpoint,
+    dashboardUrl: process.env.FIDJ_DASHBOARD_URL || "https://fidj.ovh",
+    title: process.env.APP_TITLE || "My workspace",
+    localDemo:
+      process.env.LOCAL_DEMO === "true" &&
+      host === "127.0.0.1" &&
+      ["localhost", "127.0.0.1"].includes(api.hostname),
+  };
+  createApp(settings, {
+    dataDir: process.env.FIDJ_DATA_DIR,
+    adapterKey: process.env.FIDJ_PRIVACY_ADAPTER_KEY,
+  }).listen(port, host, () =>
+    console.log(`${settings.title}: http://${host}:${port}`),
+  );
+}

package/generators/app/templates/typescript/server/privacy-adapter.ts

@@ -0,0 +1,21 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+export function verifyPrivacyRequest(
+  key: string | undefined,
+  timestamp: string,
+  signature: string,
+  payload: unknown,
+) {
+  if (
+    !key ||
+    key.length < 32 ||
+    !/^\d+$/.test(timestamp) ||
+    Math.abs(Date.now() - Number(timestamp)) > 300000 ||
+    !/^[a-f0-9]{64}$/.test(signature)
+  )
+    return false;
+  const expected = createHmac("sha256", key)
+    .update(timestamp + "." + JSON.stringify(payload))
+    .digest();
+  return timingSafeEqual(expected, Buffer.from(signature, "hex"));
+}