@odeva/cli 0.0.3 → 0.0.4

package/README.md

@@ -101,6 +101,14 @@ port = 3000
 [access_scopes]
 scopes = ["reservations:read", "reservations:write"]
 
+# Omit this section if the app doesn't surface inside the merchant admin.
+[admin]
+entry_url = "https://app.example.com/admin"
+
+[admin.sidebar]
+label = "Cabin Manager"
+icon = "puzzle"
+
 [webhooks]
 api_version = "2026-01"
 
@@ -115,6 +123,76 @@ uri = "/webhooks/payment.succeeded"
 
 This file is the source of truth for app config. `odeva app config link` pushes it to the platform; `odeva app dev` reads webhook subscriptions from it to wire up the tunnel.
 
+## Embedding apps in the merchant admin
+
+The admin embed surface lets your app appear as a sidebar entry inside the Odeva merchant admin, mounting your UI in an iframe. It is opt-in: the feature activates only when you declare an `[admin]` block in `odeva.app.toml` (see the Config example above) and run `odeva app config link`.
+
+### How it works
+
+1. Developer declares `[admin]` in `odeva.app.toml` (see the Config example above) and runs `odeva app config link`.
+2. Merchant installs the app from the marketplace.
+3. Merchant clicks the sidebar entry. `odeva-admin` mints a 5-min EdDSA session token via the `mintAppSessionToken` GraphQL mutation, then loads the iframe at `entry_url?session_token=<jwt>&host=<base_url>`.
+4. The app verifies the token against the platform JWKS at `/.well-known/odeva/apps/jwks.json`, checking `iss` and `aud`.
+5. Before the token expires, the app's **backend** calls `POST /api/apps/session-token/refresh` with `X-Api-Key: <api_key>` and hands the new token to the iframe.
+
+### Session token claims
+
+Tokens are standard JWTs signed with `EdDSA`; the JOSE header carries `alg`, `typ`, and `kid`.
+
+| Claim | Value |
+| --- | --- |
+| `iss` | Platform base URL (matches your `ODEVA_API_URL`) |
+| `aud` | The app's `client_id` (matches your `ODEVA_APP_CLIENT_ID`) |
+| `sub` | The app installation ID (string) |
+| `org_id` | The merchant organization ID (string) |
+| `app_id` | The app ID (string) |
+| `exp` | 5 minutes after `iat` |
+| `iat` | Issued-at (unix seconds) |
+| `jti` | Unique token nonce |
+
+### Verifying the token
+
+The JWKS endpoint is `${ODEVA_API_URL}/.well-known/odeva/apps/jwks.json`. The scaffolded template (`odeva app init`) provides a reference implementation in `src/admin.ts`; it uses the `jose` library with `createRemoteJWKSet` and `jwtVerify`.
+
+Key points when verifying:
+
+- Check `iss` matches your `ODEVA_API_URL`.
+- Check `aud` matches your `ODEVA_APP_CLIENT_ID`.
+- Never accept `alg: "none"` — `jose`'s `createRemoteJWKSet` enforces this automatically; if you roll your own verifier you must enforce it yourself.
+
+### Refreshing the token
+
+Tokens have a 5-minute TTL. Long-lived iframe sessions must refresh the token before it expires.
+
+Refresh from the app's **backend** only — the `api_key` must not be exposed to the browser.
+
+```sh
+curl -X POST "$ODEVA_API_URL/api/apps/session-token/refresh" \
+  -H "X-Api-Key: $ODEVA_API_KEY"
+# -> { "token": "...", "expires_at": "2026-..." }
+```
+
+Success response: `{ token, expires_at }` where `expires_at` is an ISO8601 timestamp.
+
+Error codes:
+
+| Status | Meaning |
+| --- | --- |
+| `401` | Missing, invalid, or revoked `api_key` |
+| `403` | `api_key` is not an app-installation key (e.g. a merchant key) |
+| `409` | Installation is not active, or the app has no `[admin]` declared |
+| `503` | Platform signing key not configured (operator-side; retry) |
+
+Typical pattern: the backend refreshes ~30 s before `expires_at` and pushes the new token to the iframe via your own channel (postMessage, polling, or whatever fits the app).
+
+### Quick reference
+
+- JWKS: `${ODEVA_API_URL}/.well-known/odeva/apps/jwks.json`
+- Refresh: `${ODEVA_API_URL}/api/apps/session-token/refresh`
+- Reference implementation: `src/admin.ts` (scaffolded by `odeva app init`)
+- Env vars: `ODEVA_API_URL`, `ODEVA_APP_CLIENT_ID`, `ODEVA_API_KEY`
+- Not yet shipped: host↔app `postMessage` bridge, URL sync between iframe and host.
+
 ## Templates
 
 Bundled templates live under `templates/` in this repo:

package/dist/commands/app/config/link.js

@@ -1,10 +1,28 @@
 import { Command, Flags } from "@oclif/core";
 import * as p from "@clack/prompts";
 import { OdevaApi } from "../../../lib/api.js";
-import { loadAppConfig, saveAppConfig } from "../../../lib/config.js";
+import { loadAppConfig, saveAppConfig, ADMIN_ICONS } from "../../../lib/config.js";
 import { saveAppEnv } from "../../../lib/app-env.js";
 import { withErrorHandling } from "../../../lib/run.js";
 import { ui } from "../../../lib/ui.js";
+import { CliError } from "../../../lib/errors.js";
+function buildAdminEmbedInput(admin, configPath) {
+  const validIcons = ADMIN_ICONS;
+  if (!validIcons.includes(admin.sidebar.icon)) {
+    const iconList = ADMIN_ICONS.join(", ");
+    throw new CliError(
+      `Invalid 'admin.sidebar.icon' in odeva.app.toml: '${admin.sidebar.icon}'. Must be one of: ${iconList}.`,
+      { hint: `Edit ${configPath}` }
+    );
+  }
+  return {
+    entryUrl: admin.entry_url,
+    sidebar: {
+      label: admin.sidebar.label,
+      icon: admin.sidebar.icon
+    }
+  };
+}
 class AppConfigLink extends Command {
   static description = "Register the local app on Odeva and sync its client_id back to odeva.app.toml";
   static examples = ["$ odeva app config link"];
@@ -18,6 +36,7 @@ class AppConfigLink extends Command {
     const { flags } = await this.parse(AppConfigLink);
     await withErrorHandling(this, async () => {
       const loaded = loadAppConfig();
+      const adminInput = loaded.config.admin ? buildAdminEmbedInput(loaded.config.admin, loaded.path) : void 0;
       p.intro(ui.brand("odeva app config link"));
       p.note(
         [
@@ -25,7 +44,8 @@ class AppConfigLink extends Command {
           `${ui.dim("slug:")}        ${loaded.config.slug}`,
           `${ui.dim("client_id:")}   ${loaded.config.client_id ?? ui.dim("(new)")}`,
           `${ui.dim("homepage:")}    ${loaded.config.homepage_url ?? ui.dim("(none)")}`,
-          `${ui.dim("scopes:")}      ${(loaded.config.access_scopes?.scopes ?? []).join(", ") || ui.dim("(none)")}`
+          `${ui.dim("scopes:")}      ${(loaded.config.access_scopes?.scopes ?? []).join(", ") || ui.dim("(none)")}`,
+          ...loaded.config.admin ? [`${ui.dim("admin:")}       ${loaded.config.admin.sidebar.label} (${loaded.config.admin.entry_url})`] : []
         ].join("\n"),
         "Will register this app"
       );
@@ -51,10 +71,11 @@ class AppConfigLink extends Command {
         homepageUrl: loaded.config.homepage_url,
         installUrl: loaded.config.install_url,
         privacyUrl: loaded.config.privacy_url,
-        requestedScopes: loaded.config.access_scopes?.scopes
+        requestedScopes: loaded.config.access_scopes?.scopes,
         // `webhookUrl` is the install-time URL recorded on the App; per-event
         // subscriptions are managed separately by `odeva app dev` against the
         // tunnel URL.
+        ...adminInput ? { adminEmbed: adminInput } : {}
       });
       spinner.stop(`${existingId ? "Updated" : "Registered"} app ${ui.code(app.slug)} (client_id ${ui.code(app.clientId)})`);
       loaded.config.client_id = app.clientId;
@@ -89,5 +110,6 @@ class AppConfigLink extends Command {
   }
 }
 export {
+  buildAdminEmbedInput,
   AppConfigLink as default
 };

package/dist/lib/api.js

@@ -153,6 +153,7 @@ class OdevaApi {
         $privacyUrl: String
         $requestedScopes: [String!]
         $webhookUrl: String
+        $adminEmbed: AdminEmbedInput
       ) {
         upsertDeveloperApp(
           id: $id
@@ -165,6 +166,7 @@ class OdevaApi {
           privacyUrl: $privacyUrl
           requestedScopes: $requestedScopes
           webhookUrl: $webhookUrl
+          adminEmbed: $adminEmbed
         ) {
           app {
             id

package/dist/lib/config.js

@@ -3,6 +3,17 @@ import { dirname, join, resolve } from "node:path";
 import { parse, stringify } from "smol-toml";
 import { APP_CONFIG_FILE } from "./paths.js";
 import { AppConfigNotFoundError, CliError } from "./errors.js";
+const ADMIN_ICONS = [
+  "puzzle",
+  "box",
+  "plug",
+  "bot",
+  "sparkles",
+  "wrench",
+  "database",
+  "bar-chart",
+  "wallet"
+];
 function findAppConfigPath(startDir = process.cwd()) {
   let dir = resolve(startDir);
   while (true) {
@@ -59,8 +70,60 @@ function validateConfig(config, path) {
       };
     });
   }
+  if (config.admin !== void 0) {
+    validateAdminSection(config.admin, path);
+  }
+}
+function validateAdminSection(admin, path) {
+  if (typeof admin !== "object" || admin === null || Array.isArray(admin)) {
+    throw new CliError(`Invalid ${APP_CONFIG_FILE}: 'admin' must be a table.`, {
+      hint: `Edit ${path}`
+    });
+  }
+  const a = admin;
+  if (typeof a["entry_url"] !== "string" || !a["entry_url"]) {
+    throw new CliError(`Invalid ${APP_CONFIG_FILE}: missing 'admin.entry_url'.`, {
+      hint: `Edit ${path}`
+    });
+  }
+  if (!a["entry_url"].startsWith("https://")) {
+    throw new CliError(
+      `Invalid 'admin.entry_url' in ${APP_CONFIG_FILE}: must start with https://.`,
+      { hint: `Edit ${path}` }
+    );
+  }
+  const sidebar = a["sidebar"];
+  if (typeof sidebar !== "object" || sidebar === null || Array.isArray(sidebar)) {
+    throw new CliError(`Invalid ${APP_CONFIG_FILE}: missing 'admin.sidebar' table.`, {
+      hint: `Edit ${path}`
+    });
+  }
+  const s = sidebar;
+  if (typeof s["label"] !== "string" || s["label"].length === 0) {
+    throw new CliError(`Invalid ${APP_CONFIG_FILE}: missing 'admin.sidebar.label'.`, {
+      hint: `Edit ${path}`
+    });
+  }
+  if (s["label"].length > 30) {
+    throw new CliError(
+      `Invalid 'admin.sidebar.label' in ${APP_CONFIG_FILE}: must be 30 characters or fewer.`,
+      { hint: `Edit ${path}` }
+    );
+  }
+  if (typeof s["icon"] !== "string" || !s["icon"]) {
+    throw new CliError(`Invalid ${APP_CONFIG_FILE}: missing 'admin.sidebar.icon'.`, { hint: `Edit ${path}` });
+  }
+  const validIcons = ADMIN_ICONS;
+  if (!validIcons.includes(s["icon"])) {
+    const iconList = ADMIN_ICONS.join(", ");
+    throw new CliError(
+      `Invalid 'admin.sidebar.icon' in ${APP_CONFIG_FILE}: '${s["icon"]}'. Must be one of: ${iconList}.`,
+      { hint: `Edit ${path}` }
+    );
+  }
 }
 export {
+  ADMIN_ICONS,
   findAppConfigPath,
   loadAppConfig,
   saveAppConfig,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@odeva/cli",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "Build apps on the Odeva booking platform — scaffold, develop, deploy.",
   "license": "MIT",
   "type": "module",

package/templates/hono-bun/README.md.tmpl

@@ -21,3 +21,22 @@ odeva webhook trigger reservation.created
 - `odeva.app.toml` — app config (name, slug, webhooks, scopes)
 - `src/index.ts` — Hono server with a webhook handler stub
 - `src/webhook.ts` — HMAC signature verification
+- `src/admin.ts` — iframe session-token verification
+
+## Embed in the merchant admin
+
+This template ships a `/admin` route that verifies Odeva session tokens against
+the platform's JWKS. To surface your app inside the merchant admin sidebar:
+
+1. Uncomment the `[admin]` block at the bottom of `odeva.app.toml` and set
+   `entry_url` to a publicly reachable URL (your `odeva app dev` tunnel works).
+2. Run `odeva app config link` to push the embed config to Odeva.
+3. Reinstall the app on a test org; the sidebar entry appears.
+
+`/admin` reads `?session_token=<jwt>` from the iframe URL, verifies it via
+`jose` + the JWKS at `${ODEVA_API_URL}/.well-known/odeva/apps/jwks.json`,
+and renders `Hello, org <org_id>`. See `src/admin.ts` for the verification
+recipe and a comment showing how to refresh tokens server-side.
+
+Env: `ODEVA_APP_CLIENT_ID` is written into `.odeva.env` by `config link`;
+`ODEVA_API_URL` overrides the default `https://booking.odeva.app`.

package/templates/hono-bun/odeva.app.toml.tmpl

@@ -23,3 +23,16 @@ api_version = "2026-01"
 # [[webhooks.subscriptions]]
 # topic = "reservation.created"
 # uri = "/webhooks/reservation.created"
+
+# Uncomment to embed this app inside the merchant admin sidebar.
+# The merchant admin will iframe `entry_url?session_token=<short-lived JWT>`
+# and your `/admin` route verifies that token against the Odeva JWKS.
+#
+# Icons: puzzle, box, plug, bot, sparkles, wrench, database, bar-chart, wallet.
+#
+# [admin]
+# entry_url = "https://<your-app-dev-url>/admin"
+#
+# [admin.sidebar]
+# label = "{{name}}"
+# icon = "puzzle"

package/templates/hono-bun/package.json.tmpl

@@ -10,7 +10,8 @@
   },
   "dependencies": {
     "@odeva/booking-sdk": "^0.1.0",
-    "hono": "^4.6.0"
+    "hono": "^4.6.0",
+    "jose": "^6.0.0"
   },
   "devDependencies": {
     "@types/bun": "^1.1.0",

package/templates/hono-bun/src/admin.ts

@@ -0,0 +1,99 @@
+// Admin embed route. The Odeva merchant admin iframes this route with
+// `?session_token=<short-lived EdDSA JWT>`. We verify the token against
+// the platform's JWKS and render a personalised page for the org.
+//
+// Opt in by uncommenting the `[admin]` block in `odeva.app.toml` and
+// running `odeva app config link`.
+
+import { Hono } from "hono";
+import { createRemoteJWKSet, jwtVerify } from "jose";
+
+const ODEVA_API_URL = process.env.ODEVA_API_URL ?? "https://booking.odeva.app";
+const ODEVA_APP_CLIENT_ID = process.env.ODEVA_APP_CLIENT_ID;
+
+// Lazily initialised on first request so module load stays side-effect-free.
+let _jwks: ReturnType<typeof createRemoteJWKSet> | null = null;
+
+function getJwks(): ReturnType<typeof createRemoteJWKSet> {
+  if (!_jwks) {
+    _jwks = createRemoteJWKSet(
+      new URL("/.well-known/odeva/apps/jwks.json", ODEVA_API_URL),
+    );
+  }
+  return _jwks;
+}
+
+// Cheap HTML escaping — values come from a verified JWT (Odeva-issued) but
+// defence costs nothing.
+function escape(s: string): string {
+  return s
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+
+export const adminApp = new Hono();
+
+adminApp.get("/", async (c) => {
+  if (!ODEVA_APP_CLIENT_ID) {
+    return c.text(
+      "Server is missing ODEVA_APP_CLIENT_ID. " +
+        "Set it via `.odeva.env` (managed by `odeva app config link`).",
+      500,
+    );
+  }
+
+  const token = c.req.query("session_token");
+  if (!token) {
+    return c.text("Missing session_token query parameter.", 400);
+  }
+
+  // Session tokens are short-lived (5 minutes). To refresh from your backend,
+  // POST to the refresh endpoint with your installation's api_key:
+  //
+  //   const res = await fetch(`${process.env.ODEVA_API_URL}/api/apps/session-token/refresh`, {
+  //     method: "POST",
+  //     headers: { "X-Api-Key": installationApiKey },
+  //   });
+  //   const { token, expires_at } = await res.json();
+  //
+  // The api_key is the one Odeva minted at install time (see src/install.ts).
+  // NEVER call this from the iframe — the api_key would be exposed to the
+  // browser. Mint a fresh token server-side and hand it to your frontend.
+
+  let payload: { org_id?: unknown; sub?: string };
+  try {
+    const result = await jwtVerify(token, getJwks(), {
+      issuer: ODEVA_API_URL,
+      audience: ODEVA_APP_CLIENT_ID,
+    });
+    payload = result.payload as { org_id?: unknown; sub?: string };
+  } catch {
+    return c.text("Invalid session token.", 401);
+  }
+
+  const rawOrgId = payload.org_id;
+  const rawSub = payload.sub;
+  if (
+    typeof rawOrgId !== "string" ||
+    !rawOrgId ||
+    typeof rawSub !== "string" ||
+    !rawSub
+  ) {
+    return c.text("Invalid session token.", 401);
+  }
+  const orgId = escape(rawOrgId);
+  const installationId = escape(rawSub);
+
+  return c.html(`
+    <!doctype html>
+    <html><head><title>{{name}}</title></head>
+    <body style="font-family: system-ui; max-width: 32rem; margin: 4rem auto; padding: 0 1rem;">
+      <h1>Hello, org ${orgId}</h1>
+      <p>This page was rendered by your app inside the merchant admin iframe.</p>
+      <p>Installation: <code>${installationId}</code></p>
+    </body></html>
+  `);
+});

package/templates/hono-bun/src/index.ts

@@ -4,6 +4,7 @@ import { verifyWebhook } from "./webhook.js";
 import { makeInstallHandler } from "./install.js";
 import { SqliteInstallationStore } from "./installations.js";
 import { logger } from "./logger.js";
+import { adminApp } from "./admin.js";
 
 // Default store: SQLite file next to the app. Swap to your own
 // `InstallationStore` impl (e.g. Postgres) for multi-instance deploys.
@@ -15,7 +16,7 @@ app.get("/", (c) =>
   c.json({
     app: "{{slug}}",
     ok: true,
-    routes: ["GET /", "GET /healthz", "GET /install", "GET /sdk/accommodations", "POST /webhooks/:topic"],
+    routes: ["GET /", "GET /healthz", "GET /install", "GET /sdk/accommodations", "GET /admin", "POST /webhooks/:topic"],
   }),
 );
 
@@ -46,6 +47,10 @@ app.get("/sdk/accommodations", async (c) => {
 // Install handshake. Odeva redirects here with `?install_code=...`.
 app.get("/install", makeInstallHandler(installations));
 
+// Admin embed. Verifies the session_token JWT issued by Odeva and renders
+// a page inside the merchant admin sidebar iframe.
+app.route("/admin", adminApp);
+
 // Webhook handler. `odeva app dev` registers subscriptions from odeva.app.toml
 // against the dev tunnel, so payloads from the Odeva platform arrive here.
 app.post("/webhooks/:topic", async (c) => {