@lukoweb/apitogo 0.2.20 → 0.2.22

package/dist/declarations/cli/platform/client/platform-api.d.ts

@@ -413,6 +413,24 @@ export interface GatewayDryRunDto {
     activeKeys: number;
     comparedWithGateway: boolean;
 }
+export interface ProjectIdentityDto {
+    status: string;
+    issuer: string;
+    clientId: string;
+    audience: string;
+    portalRedirectUris: string[];
+    errorCode?: string | null;
+    errorMessage?: string | null;
+    nativeSignup: boolean;
+}
+export interface ProjectIdentityRequestBody {
+    audience?: string;
+    portalRedirectUris: string[];
+    nativeSignup?: boolean;
+}
+export interface DevPortalIdentityLinkDto {
+    jobId: string;
+}
 export interface GatewayTeardownAcceptedDto {
     reconciliationId: string;
     state: string;
@@ -521,6 +539,10 @@ export declare class PlatformApiClient {
         spec?: string;
     }): Promise<GatewayDryRunDto>;
     deleteGateway(projectId: string): Promise<GatewayTeardownAcceptedDto>;
+    putProjectIdentity(projectId: string, body: ProjectIdentityRequestBody): Promise<ProjectIdentityDto>;
+    getProjectIdentity(projectId: string): Promise<ProjectIdentityDto | null>;
+    deleteProjectIdentity(projectId: string): Promise<ProjectIdentityDto | null>;
+    linkDevPortalIdentity(projectId: string): Promise<DevPortalIdentityLinkDto>;
     getDevPortalBackend(projectId: string): Promise<DevPortalBackendDto | null>;
     getDevPortalSetupStatus(projectId: string): Promise<DevPortalSetupStatusDto>;
     getDevPortalSettings(projectId: string): Promise<DevPortalSettingsDto | null>;

package/dist/declarations/cli/platform/tools/lifecycle.d.ts

@@ -10,6 +10,7 @@ export declare function resolveBootstrapProjectId(client: PlatformApiClient, arg
     name: string;
     description?: string;
     modules: string[];
+    projectId?: string;
 }, steps: BootstrapStep[]): Promise<{
     projectId: string;
     resumed: boolean;
@@ -30,6 +31,8 @@ export declare function handleBootstrapProject(client: PlatformApiClient, config
     oidcAudiences?: string[];
     limitsJson?: string;
     publicHealthActionKey?: string;
+    projectId?: string;
+    onProjectResolved?: (projectId: string) => Promise<void> | void;
 }, progress?: ProgressReporter): Promise<string>;
 export declare function handleTeardownProject(client: PlatformApiClient, config: ApitogoConfig, args: {
     projectId?: string;

package/docs/configuration/gateway.md

@@ -0,0 +1,221 @@
+---
+title: Protect your API with the gateway
+description:
+  Put the APItoGo gateway in front of an API you already host. What each setting means, where to
+  find the login values (OIDC), and how to write the rules yourself.
+sidebar_icon: shield
+---
+
+The **gateway** sits in front of an API you already host. It checks who is calling, limits how
+often, and passes only the calls you allow to your API. You do not move your API.
+
+```
+ callers ──► APItoGo gateway ──► your API (stays where it is)
+              │  checks the login token
+              │  limits calls
+              │  allows only the calls in your OpenAPI file
+              └  your real API address stays hidden
+```
+
+You set it up in one file, `apitogo.config.json`, in a `gateway` section.
+
+## The smallest setup
+
+```json
+{
+  "version": 2,
+  "gateway": {
+    "origin": { "mode": "proxy", "url": "https://api.example.com", "healthPath": "/health" },
+    "specs": ["apis/openapi.yaml"],
+    "auth": {
+      "mode": "oidc",
+      "metadataUrl": "https://login.example.com/.well-known/openid-configuration",
+      "issuers": ["https://login.example.com/"],
+      "audiences": ["my-api"]
+    },
+    "policies": {
+      "access": { "jwt": true, "apiKey": false },
+      "rateLimit": { "calls": 60, "periodSeconds": 60 },
+      "operations": { "public": ["GET /health"] }
+    }
+  }
+}
+```
+
+`apitogo add gateway` writes the first part for you. The rest you write yourself, and the sections
+below explain every value.
+
+## 1. Your API (`origin` and `specs`)
+
+| Setting             | What to put there                                                                  | Where to get it                                                  |
+| ------------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| `origin.mode`       | `proxy`: your API stays where it is.                                               | Always `proxy` for an API you host.                              |
+| `origin.url`        | The address of your API. It must be `https://`.                                    | You already know it. It is where your API answers today.         |
+| `origin.healthPath` | A path the platform can call to see that your API is alive, for example `/health`. | A cheap call on your API that needs no login.                    |
+| `specs`             | The OpenAPI file or files that describe your API.                                  | Your API's `openapi.yaml`, or the file your framework generates. |
+
+The gateway only lets through the calls listed in your OpenAPI file. A call that is not in the file
+is refused, so a forgotten path never leaks.
+
+## 2. Who may call (`auth`)
+
+With `"mode": "oidc"` the caller sends a **login token** (a JWT) with each call:
+`Authorization: Bearer <token>`. The token comes from your own login provider, for example Auth0,
+Microsoft Entra ID, Okta or Keycloak. The gateway checks that the token is genuine, is from your
+provider and is meant for your API.
+
+You must give **all three** of these values. If one is missing, the deploy is blocked, so a settings
+mistake can never leave your API open.
+
+| Setting       | What it is                                                                                            | How to find it                                                |
+| ------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| `metadataUrl` | The address where the gateway reads your provider's public keys, so it can check a token's signature. | Your issuer address plus `/.well-known/openid-configuration`. |
+| `issuers`     | Who is allowed to issue tokens. It must match the `iss` value in your tokens **exactly**.             | The `issuer` field inside the metadata document (see below).  |
+| `audiences`   | Who the token is meant for. It must match the `aud` value in your tokens.                             | The identifier you gave your API at your provider.            |
+
+### Find the values in four steps
+
+1. **Find your provider's issuer address.** It is on the provider's dashboard or in its docs.
+   Typical shapes are in the table below.
+2. **Open the metadata address in a browser.** Add `/.well-known/openid-configuration` to the issuer
+   address. You see a JSON document. If you see an error, the address is wrong.
+3. **Copy the `issuer` value from that document** into `issuers`, character for character, including
+   a trailing `/` if it has one.
+4. **Use the identifier of your API as `audiences`.** You create this identifier at your provider
+   when you register your API. It is often called _API identifier_, _audience_ or _application ID
+   URI_.
+
+### Typical values by provider
+
+These are typical shapes. Always confirm them in your provider's dashboard.
+
+| Provider           | Issuer                                                                        | Audience                                                       |
+| ------------------ | ----------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| Auth0              | `https://YOUR-TENANT.auth0.com/` (with the trailing `/`)                      | The _API identifier_ of your API in Auth0                      |
+| Microsoft Entra ID | `https://login.microsoftonline.com/TENANT-ID/v2.0`                            | Your API's _Application ID URI_, for example `api://CLIENT-ID` |
+| Okta               | `https://YOUR-ORG.okta.com/oauth2/default` (or your own authorization server) | The audience set on that authorization server                  |
+| Keycloak           | `https://HOST/realms/YOUR-REALM`                                              | The client or audience you configured for your API             |
+
+In every case the metadata address is the issuer plus `/.well-known/openid-configuration`.
+
+### Check a real token
+
+Ask your provider for a token for your API, then read what is inside it. The values `iss` and `aud`
+must match your `issuers` and `audiences`:
+
+```bash
+node -p "JSON.parse(Buffer.from(process.argv[1].split('.')[1],'base64url').toString())" "PASTE-THE-TOKEN-HERE"
+```
+
+A token is a login credential. Read it on your own computer, as above, and never share it.
+
+### The most common mistakes
+
+| What you see                                                      | Usual cause                                                                                                |
+| ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| Every call answers `401` although the token looks right           | `issuers` or `audiences` does not match `iss` or `aud` in the token. A trailing `/` is enough to break it. |
+| `apitogo check` or `deploy` says the auth settings are incomplete | One of `metadataUrl`, `issuers` or `audiences` is empty. All three are needed.                             |
+| The metadata address shows an error in the browser                | The issuer address is wrong, or your provider uses a different path. Check its docs.                       |
+
+> **Not available yet:** `"mode": "identity"` (APItoGo's own sign-up and login for your end users)
+> is a planned service. For now, use `oidc` with your own provider.
+
+## 3. The rules (`policies`)
+
+Rules go in `gateway.policies`. Write them by hand: they are a few lines each.
+
+### `access`: who gets in
+
+```json
+"access": { "jwt": true, "apiKey": false }
+```
+
+| Setting  | Effect                                                                                                                        |
+| -------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `jwt`    | `true`: a valid login token is required.                                                                                      |
+| `apiKey` | `true`: a key in the `Ocp-Apim-Subscription-Key` header is required. Keys need the plans service, which is not available yet. |
+
+Set `access` yourself and do not rely on the default.
+
+### `operations`: open a call to everyone, or close it
+
+```json
+"operations": { "public": ["GET /health"], "deny": ["DELETE /orders"] }
+```
+
+Each entry is `METHOD /path`, exactly as in your OpenAPI file.
+
+| List     | Effect                                                                               |
+| -------- | ------------------------------------------------------------------------------------ |
+| `public` | Anyone can call it, with no token. Use it for a health check or a public price list. |
+| `deny`   | The gateway always refuses it, even with a valid token.                              |
+
+Every other call needs a login.
+
+### `rateLimit` and `quota`: how often
+
+```json
+"rateLimit": { "calls": 60, "periodSeconds": 60 },
+"quota": { "calls": 10000, "periodDays": 30 }
+```
+
+| Setting     | Effect                                                                                                                 |
+| ----------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `rateLimit` | At most `calls` calls in every `periodSeconds` seconds. Extra calls get `429`. Use it to protect your API from bursts. |
+| `quota`     | At most `calls` calls in every `periodDays` days. Use it for a monthly allowance.                                      |
+
+### `cors`: which websites may call from a browser
+
+```json
+"cors": ["https://app.example.com"]
+```
+
+A browser only lets a web page call your API if the API allows that page's site. List each site as
+`https://host` only: no path and no trailing `/`. An entry like `https://app.example.com/` is
+refused by `apitogo check`.
+
+### Keep your API from being called directly
+
+Your API has a public address, so someone could skip the gateway. Make your API accept calls only
+with a secret that only the gateway sends:
+
+```json
+"origin": {
+  "mode": "proxy",
+  "url": "https://api.example.com",
+  "auth": { "type": "header", "name": "X-Gateway-Secret", "value": "secret:GATEWAY_SECRET" }
+}
+```
+
+```bash
+npx apitogo secrets set GATEWAY_SECRET
+```
+
+The value is a reference, never the secret itself. The secret is stored encrypted and never shown
+again. Then make your API refuse any call without that header.
+
+## 4. Try it and check it
+
+Run these before you deploy:
+
+```bash
+npx apitogo check
+npx apitogo plan
+```
+
+`check` finds mistakes in the file, offline. `plan` shows what a deploy would change and changes
+nothing. Then deploy and test the address that `apitogo status` shows:
+
+```bash
+npx apitogo deploy --only gateway
+curl -i https://YOUR-GATEWAY-ADDRESS/health
+curl -i https://YOUR-GATEWAY-ADDRESS/orders
+```
+
+| Answer                          | Meaning                                                       |
+| ------------------------------- | ------------------------------------------------------------- |
+| `200` on a public call          | The call is open and your API answered.                       |
+| `401` on a call without a token | The gateway is protecting that call.                          |
+| `404`                           | The path is not in your OpenAPI file.                         |
+| `429`                           | The rate limit was reached.                                   |
+| `502` or `504`                  | Your API did not answer. Check `origin.url` and `healthPath`. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lukoweb/apitogo",
-  "version": "0.2.20",
+  "version": "0.2.22",
   "type": "module",
   "sideEffects": [
     "**/*.css",

package/src/config/v2/index.ts

@@ -61,6 +61,8 @@ export {
   serviceReady,
   stubManifest,
   withGatewayEntry,
+  withIdentityEntry,
+  withPlansEntry,
   withPortalEntry,
   writeManifest,
 } from "./manifest.js";

package/src/config/v2/manifest.ts

@@ -319,6 +319,95 @@ export function withGatewayEntry(
   };
 }
 
+/**
+ * Adds the identity entry an identity deploy learned: the issuer address, the portal's sign-in client and the audience
+ * of its tokens. Public values only. Entries of other services are kept as they are.
+ */
+export function withIdentityEntry(
+  existing: ServiceManifest | undefined,
+  info: {
+    projectId: string;
+    projectName: string;
+    /** `apitogo` for the platform's own identity, `oidc` for the customer's provider (nothing is made for it). */
+    provider?: "apitogo" | "oidc";
+    issuer: string;
+    clientId: string;
+    audience?: string;
+    nativeSignup: boolean;
+    now?: Date;
+  },
+): ServiceManifest {
+  const base: ServiceManifest =
+    existing ??
+    parseManifest({
+      schemaVersion: SUPPORTED_MANIFEST_SCHEMA,
+      project: { name: info.projectName },
+    });
+  return {
+    ...base,
+    schemaVersion: SUPPORTED_MANIFEST_SCHEMA,
+    generatedAt: (info.now ?? new Date()).toISOString(),
+    preview: undefined,
+    project: { ...base.project, id: info.projectId, name: info.projectName },
+    services: {
+      ...base.services,
+      identity: {
+        ...base.services.identity,
+        provider: info.provider ?? "apitogo",
+        status: "ready",
+        issuer: info.issuer.replace(/\/+$/, ""),
+        clientId: info.clientId,
+        scopes: ["openid", "profile", "email"],
+        ...(info.audience ? { audience: info.audience } : {}),
+        capabilities: { nativeSignup: info.nativeSignup },
+      },
+    },
+  };
+}
+
+/**
+ * Adds the plans entry a plans deploy learned: where the portal reaches the plans backend and what it can do. Public
+ * values only. Entries of other services are kept as they are.
+ */
+export function withPlansEntry(
+  existing: ServiceManifest | undefined,
+  info: {
+    projectId: string;
+    projectName: string;
+    apiBaseUrl: string;
+    billing: string;
+    catalogRevision: number;
+    capabilities: Record<string, boolean>;
+    now?: Date;
+  },
+): ServiceManifest {
+  const base: ServiceManifest =
+    existing ??
+    parseManifest({
+      schemaVersion: SUPPORTED_MANIFEST_SCHEMA,
+      project: { name: info.projectName },
+    });
+  return {
+    ...base,
+    schemaVersion: SUPPORTED_MANIFEST_SCHEMA,
+    generatedAt: (info.now ?? new Date()).toISOString(),
+    preview: undefined,
+    project: { ...base.project, id: info.projectId, name: info.projectName },
+    services: {
+      ...base.services,
+      plans: {
+        ...base.services.plans,
+        provider: "apitogo",
+        status: "ready",
+        apiBaseUrl: info.apiBaseUrl.replace(/\/+$/, ""),
+        billing: info.billing,
+        catalogRevision: info.catalogRevision,
+        capabilities: info.capabilities,
+      },
+    },
+  };
+}
+
 /** Replaces `services.json` atomically. Public values only: this file ships inside the portal. */
 export async function writeManifest(
   state: Pick<StatePaths, "dir">,

package/src/config/v2/services.ts

@@ -120,7 +120,8 @@ const PLAN_TEMPLATES: Record<"free" | "tiered" | "none", unknown[]> = {
       displayName: "Free",
       default: true,
       limits: {
-        rateLimit: { calls: 10, periodSeconds: 60 },
+        // The platform's Free tier allows at most 3 calls per 60 seconds per plan; a higher number is refused.
+        rateLimit: { calls: 3, periodSeconds: 60 },
         quota: { calls: 1000, periodDays: 30 },
       },
     },
@@ -131,7 +132,8 @@ const PLAN_TEMPLATES: Record<"free" | "tiered" | "none", unknown[]> = {
       displayName: "Free",
       default: true,
       limits: {
-        rateLimit: { calls: 10, periodSeconds: 60 },
+        // The platform's Free tier allows at most 3 calls per 60 seconds per plan; a higher number is refused.
+        rateLimit: { calls: 3, periodSeconds: 60 },
         quota: { calls: 1000, periodDays: 30 },
       },
     },

package/src/vite/config.ts

@@ -19,7 +19,7 @@ import { loadDevPortalViteDefines } from "./dev-portal-env.js";
 import { findPackageRoot } from "./package-root.js";
 import { ensurePagefindDevStub } from "./pagefind-dev-stub.js";
 import vitePlugin from "./plugin.js";
-import { stateIgnore } from "./watch-ignore.js";
+import { devServerAllow, stateIgnore } from "./watch-ignore.js";
 import { getZuploSystemConfigurations } from "./zuplo.js";
 
 /** Resolved absolute public directory (Vite default: `<root>/public`). */
@@ -144,7 +144,7 @@ export async function getViteConfig(
       middlewareMode: true,
       open: true,
       fs: {
-        allow: [dir, path.dirname(dir)],
+        allow: devServerAllow(dir, config.__meta.moduleDir),
       },
       watch: {
         ignored: [

package/src/vite/watch-ignore.ts

@@ -14,6 +14,29 @@ const within = (base: string, file: string) =>
 
 const unique = (paths: string[]) => [...new Set(paths)];
 
+/** Whether `root` is the site root (`<state>/generated`) of a config version 2 workspace: it has the `content` link. */
+function isWorkspace(root: string): boolean {
+  try {
+    return (
+      path.basename(root) === "generated" &&
+      lstatSync(path.join(root, "content")).isSymbolicLink()
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The tenant's own folder of a config version 2 workspace (what `content` links to), or `undefined` for any other
+ * project. The site root sits inside the state folder, so the folder that holds `node_modules` and the pages is
+ * outside it and the dev server has to be told it may serve files from there.
+ */
+export function tenantDir(root: string): string | undefined {
+  return isWorkspace(root)
+    ? realpathSync(path.join(root, "content"))
+    : undefined;
+}
+
 /**
  * What the dev server's watcher must leave alone in a config version 2 workspace, or `undefined` for any other
  * project. The watcher meets the state folder twice: below the `content` link and, after resolving the link,
@@ -23,15 +46,7 @@ const unique = (paths: string[]) => [...new Set(paths)];
 export function stateIgnore(
   root: string,
 ): ((file: string) => boolean) | undefined {
-  let workspace = false;
-  try {
-    workspace =
-      path.basename(root) === "generated" &&
-      lstatSync(path.join(root, "content")).isSymbolicLink();
-  } catch {
-    workspace = false;
-  }
-  if (!workspace) return undefined;
+  if (!isWorkspace(root)) return undefined;
 
   const state = path.dirname(root);
   const states = unique([state, realpathSync(state)]);
@@ -43,3 +58,13 @@ export function stateIgnore(
     return STATE_INSIDE_CONTENT.test(file);
   };
 }
+
+/**
+ * The folders the dev server may serve files from. The site root of a config version 2 workspace sits inside the
+ * state folder, so the package (`node_modules`) and the tenant's pages are outside it. Without them the page's main
+ * script fails with "Failed to load url ... Does the file exist?" and the server stops.
+ */
+export function devServerAllow(root: string, moduleDir: string): string[] {
+  const tenant = tenantDir(root);
+  return [root, path.dirname(root), moduleDir, ...(tenant ? [tenant] : [])];
+}