@ofidj/generator-fidj 1.0.0 → 1.0.3

package/generators/app/templates/typescript/README.md

@@ -0,0 +1,82 @@
+# Your Fidj TypeScript app
+
+A generated TypeScript client with Fidj sign-in and app-scoped privacy. The generator selects the mode from its inputs:
+
+- With `--content`: public HTML plus account/privacy controls, built to static `www/` assets and optional `CNAME`. No app backend is required; the client calls Fidj directly.
+- Without `--content`: Studio Notes, with a Node backend enforcing live Owner/Editor roles for private notes.
+
+The public title, welcome, HTML content and endpoints are in `app.config.json`. Edit the original generator command and regenerate for repeatable changes. Content HTML is trusted developer source.
+
+## Run
+
+Use Node 22 or later. Copy `.env.example` to `.env`, set the public app ID and Fidj API URL, then:
+
+```sh
+npm install
+npm run build
+npm start
+```
+
+Open http://localhost:8200. For content apps, `npm run build-prod` produces static `www/` assets; the Node process is only an optional preview. For Studio Notes, the backend must run for protected operations. Configure Fidj’s allowed origins for your app domain. No app signing key belongs in the browser or this starter’s public configuration.
+
+The current unreleased generator requires the matching `@ofidj/node` 3.6.24 SDK. Until publication, generate with `--sdk-path /absolute/path/to/fidj-node/dist` after building that SDK. Local file dependencies belong only in generated development output; use registry dependencies for release.
+
+## Structure
+
+- `src/content.ts`: static content app account, live roles and privacy controls.
+- `src/main.ts`: `FidjNodeService.init`, login, browser session and views.
+- `server/index.ts`: `verifyAppSession` on every protected request; live roles decide whether a note can be saved. Changing a role takes effect on the next backend request, even if a browser still displays old roles.
+- `test/server.test.mjs`: fresh HTTP servers verify role changes, revoked/foreign sessions, outage failure, per-user notes and privacy scope.
+- `scripts/build.mjs`: browser and Node builds using [esbuild](https://esbuild.github.io/getting-started/), with a separate TypeScript typecheck.
+
+Use TDD: add and run a failing behavior test before implementation (red), make it pass (green), then refactor and run `npm test`. Change maintained template source and regenerate to verify that every fresh app receives the fix.
+
+## Privacy scope
+
+Optional preferences and their history belong to this app. In the static content app, export covers the Fidj-held membership records and no independent app database exists. In Studio Notes, export includes the Fidj membership and the starter’s notes. Leaving through this app removes its Fidj membership and locally held notes. App owners must resolve ownership first.
+
+Notes persist in `FIDJ_DATA_DIR`. With the adapter registered below, direct export/departure from Fidj includes these notes. Failed erasure keeps a request in Fidj for automatic retry with backoff; people can also retry explicitly. The API pauses after eight failed automatic attempts and exposes a needs-attention state. Account-wide identity deletion, real terms/purposes and a full production retention policy remain separate integration work. The demo agreement is explicitly a placeholder, not a legal policy.
+
+The browser SDK stores the app’s session in this origin’s local storage. Use HTTPS and maintain a strict content security policy when hosting. The backend delegates signature and session-revocation validation to the configured Fidj API and fails closed when it cannot verify a session.
+
+## Local scenario
+
+For the Notes fixture only, `LOCAL_DEMO=true` with the loopback API enables synthetic Alex/Maya/Sam sign-in shortcuts. Content/module entries keep test accounts in developer documentation. These accounts must be seeded by your local Fidj API; the starter does not create accounts or seed data remotely. Alex is the owner, and the owner console can grant Maya Editor access.
+
+## Entry flow
+
+The generated content app opens on `/#/signin`. Sign in, or choose **Enter anonymously** when enabled by `--anonymous true`, to open `/#/content`, containing the supplied HTML. Signed-in users can open **My privacy** separately. Sign-out and departure return to the sign-in screen. Anonymous content is public; this navigation flow is not a security boundary for static assets.
+
+Set `--anonymous false` in the generator command to remove anonymous entry and route unsigned visitors back to sign-in. This controls navigation; static HTML/assets remain public. Put confidential content behind a server-authorized endpoint.
+
+## Application modules
+
+When generated with `--module`, successful sign-in opens the copied module configured by `moduleEntry`. It runs under `/module/` on the same origin and must validate sessions/permissions independently. Its entry contains a `fidj-signin` meta URL for returning to this shared sign-in page. Module code is public static output; user data belongs behind authorized APIs. Rebuild the maintained module source and regenerate to update it; never patch its copied files here.
+
+## Connect app data rights
+
+Set `FIDJ_PRIVACY_ADAPTER_KEY` to a private random secret of at least 32 characters. Keep it exclusively in server environments; it is separate from an app JWT signing key. Register the app on the Fidj API server:
+
+```json
+{"YOUR_APP_ID":{"url":"https://your-app.example/fidj/privacy","key":"SAME_PRIVATE_RANDOM_SECRET"}}
+```
+
+Set that JSON as `FIDJ_PRIVACY_ADAPTERS` on the API. Endpoint registration is operator-managed in this milestone. HTTPS is required; explicit local mode also permits loopback HTTP. The local workspace launcher configures Studio Notes automatically. Requests contain `appId`, `subject`, `operation` and `requestId`; headers contain a millisecond timestamp and SHA-256 HMAC of `timestamp + "." + JSON.stringify(body)`. Requests older than five minutes are rejected; redirects are not followed. The handler must return the matching `requestId` and `status: "completed"` only after durable success.
+
+Keep `FIDJ_DATA_DIR` outside public assets and generated output. Use one writer process per directory. Replace `server/data-store.ts` with a transactional database implementation for multiple instances. Do not weaken the authorization check inside note writes or the atomic erase/receipt transaction. Duplicate erasures preserve later membership data. Minimal receipts contain a hashed subject and completion timestamp; receipts older than 30 days are pruned on the next write. Backups and unregistered external data remain outside this handler’s scope.
+
+
+## Check and rehearse
+
+After starting the Notes backend with its server-only adapter secret, run `npm run privacy:check`. The signed check confirms export/erase capabilities and writable storage without accessing user records. Override `FIDJ_APP_URL` for a deployed HTTPS backend. Keep this secret out of browser configuration.
+
+Run `npm run privacy:rehearse` for an isolated temporary-store HTTP scenario covering live roles, scoped export, persistence, failure and idempotent erasure. It never points at your running data directory. Groups are managed in the Fidj owner console; direct and group roles are checked live by the backend.
+
+## Agreement at sign-in
+
+Sign-in and account creation require the unchecked service-agreement checkbox.
+Read the app's current text/version from the dialog before accepting. If the
+agreement cannot load, the form stays blocked. The API records the accepted
+version per app; optional privacy choices are separate. The app owner must replace
+the default demo agreement using the Fidj app's `configurationAsJSON.serviceAgreement`
+(`version` and `text`) before release. No generated-source edit is needed.

package/generators/app/templates/typescript/app.config.json

@@ -0,0 +1,14 @@
+{
+  "appId": "fidj-example",
+  "apiEndpoint": "https://api.sandbox.fidj.ovh/v3",
+  "dashboardUrl": "https://fidj.ovh",
+  "title": "My app",
+  "localDemo": false,
+  "allowAnonymous": true,
+  "moduleEntry": "",
+  "description": "A space to explore, with an account that puts you in control.",
+  "highlights": [],
+  "badges": [],
+  "logo": "./fidj-logo.png",
+  "favicon": "./fidj-logo.png"
+}

package/generators/app/templates/typescript/gitignore

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+.env
+.env.local
+.fidj-data/

package/generators/app/templates/typescript/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "fidj-typescript-app",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc --noEmit && node scripts/build.mjs",
+    "start": "node --env-file=.env dist/server.cjs",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "build-prod": "npm run build",
+    "privacy:check": "node --env-file=.env scripts/privacy-check.mjs",
+    "privacy:rehearse": "npm run build && node --test test/server.test.mjs"
+  },
+  "dependencies": {
+    "@ofidj/node": "^3.6.24"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "esbuild": "0.28.2",
+    "typescript": "5.9.3"
+  }
+}

package/generators/app/templates/typescript/public/index.html

@@ -0,0 +1,16 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>My workspace · Fidj</title>
+    <link rel="icon" href="/fidj-logo.png" />
+    <link rel="stylesheet" href="/main.css" />
+    <script type="module" src="/main.js"></script>
+  </head>
+  <body>
+    <div id="app">
+      <main><h1>Opening your workspace…</h1></main>
+    </div>
+  </body>
+</html>

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

@@ -0,0 +1,49 @@
+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,
+    // The design system's fonts are copied with public/; esbuild must leave
+    // their url()s alone rather than try to resolve them at build time.
+    external: ["*.woff2"],
+  }),
+  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="${escape(config.favicon)}"><link rel="stylesheet" href="./main.css"></head><body>
+  <header class="topbar"><a class="brand" href="#/content"><img src="${escape(config.logo)}" alt="">${escape(config.title)}</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");
+  }
+}