@aircloudhq/web 1.0.0 → 1.0.4

package/README.md

@@ -0,0 +1,119 @@
+# @aircloudhq/web
+
+The application package of an Air-Cloud product: what a product's site and its JavaScript functions
+import to render pages, format values and speak the product's languages. It brings the Rails Action View
+helpers to the browser and to functions, one module per Rails helper module, under the names a Rails
+developer already knows (`numberToCurrency`, `timeAgoInWords`, `t`, `l`, and the `LinkTo` and
+`FormWith` components).
+
+- **Pages from your models.** `resourcePage("pet")` renders list, show, create, edit and delete for an
+  entity from the resource projection the platform derives from `db/schema/pet.toml`. Adding a field to
+  the schema changes the page with no edit to the view.
+- **I18n.** Translations come from the locale bundle the platform compiles from `config/locales/`, with
+  Rails' lazy lookup: `t(".title")` in `pages/home/index.jsx` reads `home.index.title`. Plurals, dates,
+  numbers and currencies follow CLDR for every locale the product declares.
+- **The same helpers in functions.** `@aircloudhq/web/function` gives a function the caller's locale,
+  so its error messages answer in the language of the request.
+- **React bindings.** `@aircloudhq/web/react` carries the router, layouts, links and form components.
+
+A product created with `aircloud new` already depends on this package, at the version the platform
+builds and tests with. You rarely add it by hand.
+
+## Install
+
+```sh
+npm install @aircloudhq/web
+```
+
+It needs the Node.js release its `engines` field names (the platform's pinned line), and React 19.2.7 or later for
+the React bindings.
+
+## Usage
+
+The site entry point `aircloud new` generates (`app/site/src/main.jsx`) renders the product's routes
+inside its layouts, with the locale bundle and the resource projection:
+
+```jsx
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { I18nProvider, SiteRouter } from "@aircloudhq/web/react";
+import bundle from "../.aircloud/locale-bundle.json";
+import projection from "../.aircloud/resource-projection.json";
+import routes from "./routes.js";
+
+// Every src/layouts/<name>.jsx, by name (`application` is the default layout).
+const layouts = Object.fromEntries(
+  Object.entries(import.meta.glob("./layouts/*.jsx", { eager: true })).map(([file, module]) => [
+    file.slice(file.lastIndexOf("/") + 1, -4),
+    module.default,
+  ]),
+);
+
+createRoot(document.getElementById("root")).render(
+  <StrictMode>
+    <I18nProvider bundle={bundle}>
+      <SiteRouter routes={routes} layouts={layouts} projection={projection} />
+    </I18nProvider>
+  </StrictMode>,
+);
+```
+
+A page reads its strings by lazy lookup (`app/site/src/pages/home/index.jsx`):
+
+```jsx
+import { useT } from "@aircloudhq/web/react";
+
+export default function HomePage() {
+  const t = useT();
+  return (
+    <section>
+      <h1>{t(".title")}</h1>
+      <p>{t(".intro")}</p>
+    </section>
+  );
+}
+```
+
+The resource page `aircloud generate scaffold pet` writes is one line (`app/site/src/pages/pet/index.jsx`):
+
+```jsx
+import { resourcePage } from "@aircloudhq/web/react";
+
+export default resourcePage("pet");
+```
+
+A function answers in the caller's locale (`app/functions/pet/index.js`):
+
+```js
+import { i18nFor } from "@aircloudhq/web/function";
+
+async function methodNotAllowed(request) {
+  // functions.pet.errors.method_not_allowed, in the locale the request negotiates
+  const i18n = await i18nFor(request, { function: "pet" });
+  return Response.json({ error: { code: "method_not_allowed", message: i18n.t(".errors.method_not_allowed", { method: request.method }) } }, { status: 405 });
+}
+```
+
+## Modules
+
+| Import | What it carries |
+|---|---|
+| `@aircloudhq/web/react` | `SiteRouter`, `I18nProvider`, `useT`, `useSite`, `LinkTo`, `FormWith`, `resourcePage` |
+| `@aircloudhq/web/helpers/number` | `numberToCurrency`, `numberToPercentage`, `numberWithDelimiter`, … |
+| `@aircloudhq/web/helpers/date` | `timeAgoInWords`, `distanceOfTimeInWords`, `distanceOfTimeInWordsToNow` |
+| `@aircloudhq/web/helpers/text`, `…/tag`, `…/url`, `…/form`, `…/sanitize`, `…/navigation` | the Action View helper modules of the same name |
+| `@aircloudhq/web/helpers/translation` | `t` and `l` |
+| `@aircloudhq/web/i18n` | `createI18n`, the runtime of the locale bundle |
+| `@aircloudhq/web/model` | `modelName` and the model naming helpers |
+| `@aircloudhq/web/function` | `i18nFor`, for functions |
+
+## Documentation
+
+The full Rails-to-Air-Cloud map — every Action View helper and where it lives here — is the
+*Rails to Air-Cloud* reference in the Air-Cloud documentation. Its tests in a product run with
+`@aircloudhq/testing`. Questions and bug reports go to this package's issue tracker (the `bugs` link
+on its npm page).
+
+## License
+
+MIT

package/package.json

@@ -1,14 +1,36 @@
 {
   "name": "@aircloudhq/web",
-  "version": "1.0.0",
-  "description": "The Air-Cloud site application package (ADR-222): the Rails Action View helpers, the i18n runtime of the locale bundle (ADR-223), resource pages over the resource projection, and React bindings.",
+  "version": "1.0.4",
+  "description": "The application package of an Air-Cloud product: the Rails Action View helpers, i18n over the product's locale bundle, resource pages over its models, and React bindings, for its site and its JavaScript functions.",
+  "keywords": [
+    "aircloud",
+    "rails",
+    "action-view",
+    "helpers",
+    "i18n",
+    "react",
+    "site",
+    "functions"
+  ],
+  "homepage": "https://github.com/aircloudhq/packages/tree/main/aircloud-web#readme",
+  "bugs": {
+    "url": "https://github.com/aircloudhq/packages/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aircloudhq/packages.git",
+    "directory": "aircloud-web"
+  },
+  "author": "Air-Cloud",
   "license": "MIT",
   "type": "module",
   "engines": {
-    "node": ">=22.22.0"
+    "node": "^24.21.0"
   },
   "exports": {
     ".": "./src/index.js",
+    "./principal": "./src/principal.js",
+    "./assertion": "./src/assertion.js",
     "./helpers/number": "./src/helpers/number.js",
     "./helpers/date": "./src/helpers/date.js",
     "./helpers/text": "./src/helpers/text.js",
@@ -27,7 +49,9 @@
     "./package.json": "./package.json"
   },
   "files": [
-    "src/"
+    "src/",
+    "README.md",
+    "LICENSE"
   ],
   "sideEffects": false,
   "dependencies": {

package/src/assertion.js

@@ -0,0 +1,114 @@
+// @aircloudhq/web/assertion — a CONTAINER's verification of the platform principal assertion (#632
+// ADR-241 decision 4). The web-origin holds the end-user session; an authenticated request reaches the
+// Builder's container with `x-air-principal`, an ES256 JWS the platform signed under its dedicated
+// `web-origin-principal` key, and never the session cookie or a token. The container verifies it here
+// with the same semantics as the functions-host route trigger (functions/src/caps_principal.rs):
+//
+//   import { verifyPrincipal } from '@aircloudhq/web/assertion';
+//   const me = await verifyPrincipal(request);  // throws on anything but a valid assertion
+//
+// Checked: alg ES256 under a key of the principal key set (`jwksFile` — default AIR_PRINCIPAL_JWKS_FILE,
+// the file the platform projects into every container from the key set its control plane reconciles into
+// the tenant namespace; a container never fetches it, so it needs no path to a platform API), the issuer,
+// `aud` = the product host the request names, `tenant_id` = this product's tenant (default
+// AIR_TENANT_ID), a lifetime of at most 60 s that has not ended, and a well-formed principal. A rotation
+// rewrites the file: an assertion naming a kid the cached set lacks re-reads it once. Fail-closed: a
+// missing setting, an absent or malformed key set or any mismatch throws.
+
+import { readFile } from 'node:fs/promises';
+
+export const PRINCIPAL_HEADER = 'x-air-principal';
+export const PRINCIPAL_ISSUER = 'aircloud-web-origin-principal';
+/** == functions/src/caps_principal.rs MAX_ASSERTION_LIFETIME_SECS / ASSERTION_CLOCK_SKEW_SECS. */
+const MAX_LIFETIME_SECS = 60;
+const CLOCK_SKEW_SECS = 5;
+const JWKS_MAX_AGE_MS = 300_000;
+
+const cache = new Map(); // jwksFile → { keys, at }
+
+const env = (k) => (typeof process !== 'undefined' && process.env ? process.env[k] : undefined);
+
+function b64uDecode(s) {
+  return Uint8Array.from(Buffer.from(s, 'base64url'));
+}
+
+function parse(token) {
+  const parts = typeof token === 'string' ? token.split('.') : [];
+  if (parts.length !== 3) throw new Error('the principal assertion is not a compact JWS');
+  const [h, p, s] = parts;
+  const json = (seg) => JSON.parse(new TextDecoder().decode(b64uDecode(seg)));
+  return { header: json(h), claims: json(p), input: new TextEncoder().encode(`${h}.${p}`), sig: b64uDecode(s) };
+}
+
+async function readKeySet(file, now) {
+  const doc = JSON.parse(await readFile(file, 'utf8'));
+  if (!doc || !Array.isArray(doc.keys)) throw new Error(`the principal key set ${file} is not a JWK set`);
+  cache.set(file, { keys: doc.keys, at: now });
+  return doc.keys;
+}
+
+/** The key `kid` of the set at `file`: cached, re-read when stale or when the cached set lacks the kid. */
+async function keyFor(file, kid, now) {
+  const hit = cache.get(file);
+  const fresh = hit && now - hit.at < JWKS_MAX_AGE_MS;
+  let found = fresh ? hit.keys.find((k) => k.kid === kid) : undefined;
+  if (!found) found = (await readKeySet(file, now)).find((k) => k.kid === kid);
+  if (!found) throw new Error(`no principal key '${kid}' in ${file}`);
+  return found;
+}
+
+const text = (v, what) => {
+  if (v === undefined || v === null) return null;
+  if (typeof v !== 'string') throw new Error(`the assertion's ${what} is not text`);
+  return v;
+};
+
+/**
+ * Verify the platform principal assertion of `request` (a Fetch API Request, or headers) and return the
+ * end user it asserts.
+ * @param {Request|{headers: Headers}} request
+ * @param {{jwksFile?: string, tenantId?: string, issuer?: string, host?: string, now?: () => number}} [options]
+ * @returns {Promise<{sub: string, tenantId: string, orgPath: string, roles: string[], act: object|null, flash: string|null, csrf: string|null}>}
+ */
+export async function verifyPrincipal(request, options = {}) {
+  const jwksFile = options.jwksFile ?? env('AIR_PRINCIPAL_JWKS_FILE');
+  const tenantId = options.tenantId ?? env('AIR_TENANT_ID');
+  const issuer = options.issuer ?? PRINCIPAL_ISSUER;
+  const now = (options.now ?? (() => Math.floor(Date.now() / 1000)))();
+  if (!jwksFile) throw new Error('verifyPrincipal: no key-set file (AIR_PRINCIPAL_JWKS_FILE) — refusing (fail-closed)');
+  if (!tenantId) throw new Error('verifyPrincipal: no tenant (AIR_TENANT_ID) — refusing (fail-closed)');
+  const headers = request.headers;
+  const host = (options.host ?? headers.get('x-forwarded-host') ?? headers.get('host') ?? '').toLowerCase();
+  const token = headers.get(PRINCIPAL_HEADER);
+  if (!token) throw new Error('the request carries no principal assertion');
+
+  const { header, claims: c, input, sig } = parse(token);
+  if (header.alg !== 'ES256' || typeof header.kid !== 'string') throw new Error('the assertion is not ES256 with a kid');
+  const jwk = await keyFor(jwksFile, header.kid, now * 1000);
+  const { kid, alg, use, key_ops: _ops, ...material } = jwk;
+  const pub = await crypto.subtle.importKey('jwk', material, { name: 'ECDSA', namedCurve: 'P-256' }, false, ['verify']);
+  const ok = await crypto.subtle.verify({ name: 'ECDSA', hash: 'SHA-256' }, pub, sig, input);
+  if (!ok) throw new Error('the assertion does not verify');
+
+  if (c.iss !== issuer) throw new Error('the assertion names another issuer');
+  if (!host || c.aud !== host) throw new Error('the assertion is for another product host');
+  if (!Number.isInteger(c.iat) || !Number.isInteger(c.exp) || c.exp <= c.iat || c.exp - c.iat > MAX_LIFETIME_SECS) {
+    throw new Error('the assertion lifetime is out of bounds');
+  }
+  if (now >= c.exp) throw new Error('the assertion has expired');
+  if (Math.max(c.iat, c.nbf ?? 0) > now + CLOCK_SKEW_SECS) throw new Error('the assertion is not valid yet');
+  if (c.tenant_id !== tenantId) throw new Error('the assertion is for another tenant');
+  if (typeof c.org_path !== 'string' || !c.org_path.startsWith('/')) throw new Error('the assertion carries no org_path');
+  if (typeof c.sub !== 'string' || c.sub === '') throw new Error('the assertion carries no sub');
+  const roles = c.roles ?? [];
+  if (!Array.isArray(roles) || roles.some((r) => typeof r !== 'string')) throw new Error("the assertion's roles are not strings");
+  return {
+    sub: c.sub,
+    tenantId: c.tenant_id,
+    orgPath: c.org_path,
+    roles,
+    act: c.act ?? null,
+    flash: text(c.flash, 'flash'),
+    csrf: text(c.csrf, 'csrf'),
+  };
+}

package/src/principal.js

@@ -0,0 +1,58 @@
+// @aircloudhq/web/principal — the end user of a `session` route, its flash and its CSRF proof, for a
+// JavaScript function (#632 ADR-241 decision 4, plan W15.4/W15.7; the Rails `current_user`-shaped
+// principal, `flash` and `csrf_meta_tags`, ADR-221 D4).
+//
+// The web-origin holds the end-user session; the function never sees the session cookie or a token.
+// The functions host hands the guest what the platform asserted, through the
+// `aircloud:functions/principal` interface, and this module reads it:
+//
+//   import { principal, flash, setFlash, csrfMeta } from '@aircloudhq/web/principal';
+//   const me = principal();           // null on a public route
+//   const { notice } = flash();       // the message the previous request set (read once)
+//   setFlash({ notice: 'Saved' });    // the next request's message
+//   `<head>${csrfMeta()}</head>`      // the token a form or fetch sends as X-CSRF-Token
+//
+// The CSRF check is the session edge's (the web-origin): an unsafe request is accepted when its
+// `Origin` is the product's, and a client that sends no `Origin` proves it with the session's token.
+import { csrfToken as wireCsrf, current, flash as wireFlash, setFlash as wireSetFlash } from 'aircloud:functions/principal@1.0.0';
+
+const escapeAttr = (s) =>
+  String(s).replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+
+/**
+ * The end user this invocation serves, or null outside a `session` route.
+ * @returns {{sub: string, tenantId: string, orgPath: string, roles: string[], act: object|null}|null}
+ */
+export function principal() {
+  const p = current();
+  if (!p) return null;
+  return { sub: p.sub, tenantId: p.tenantId, orgPath: p.orgPath, roles: [...p.roles], act: p.act ? JSON.parse(p.act) : null };
+}
+
+/** The flash the previous request of this session set (`{}` when none) — the platform clears it. */
+export function flash() {
+  const f = wireFlash();
+  if (!f) return {};
+  try {
+    return JSON.parse(f);
+  } catch {
+    return { notice: f }; // a flash a container set as plain text
+  }
+}
+
+/** Set the flash the next request of this session reads (an object, stored as JSON). */
+export function setFlash(message) {
+  wireSetFlash(JSON.stringify(message));
+}
+
+/** The session's CSRF token, or null outside a `session` route. */
+export function csrfToken() {
+  return wireCsrf() ?? null;
+}
+
+/** The Rails `csrf_meta_tags` pair carrying the session's token; empty outside a session. */
+export function csrfMeta() {
+  const t = csrfToken();
+  if (!t) return '';
+  return `<meta name="csrf-param" content="authenticity_token" />\n<meta name="csrf-token" content="${escapeAttr(t)}" />`;
+}