@endora-commerce/mod-api-keys 0.100.0

package/docs/api_keys.md

@@ -0,0 +1,89 @@
+---
+title: api_keys
+description: Bearer-token integration credentials
+---
+
+# `api_keys`
+
+Scoped bearer-token credentials for machine-to-machine integrations. The
+plaintext token is shown once at creation; only its SHA-256 hash is stored.
+A key may additionally carry a **distributor binding**
+(Organization + Sales Channel + service Customer Account) and an optional
+expiry, turning it into a partner credential for the `/api/v1/external/*`
+namespace, which the *Partner API access* integration guide documents in full.
+
+## Public surface
+
+| Verb + Path | Audience | Purpose |
+| --- | --- | --- |
+| `GET /api/v1/admin/api-keys` | admin | List keys + last-used timestamps, binding, expiry |
+| `POST /api/v1/admin/api-keys` | admin | Create; returns the raw bearer **once** |
+| `DELETE /api/v1/admin/api-keys/:id` | admin | Revoke |
+
+External calls authenticate by sending `Authorization: Bearer sk_live_…`.
+`requireApiKey(scope)` and `requireBoundApiKey(scope)` are Fastify
+pre-handlers exposed by the `api_keys` plugin; route surfaces gate themselves
+with them (`requireApiKey('catalog:write')`,
+`requireBoundApiKey('orders:write')`, etc.).
+
+## Scope enum
+
+Creation validates scopes against the typed catalog in
+`packages/contracts/src/api-keys.ts` (`apiKeyScopeSchema`):
+
+| Scope | Meaning |
+| --- | --- |
+| `catalog:read` | PIM reads (unbound) and the external catalog surface (bound) |
+| `catalog:write` | PIM by-SKU upsert — **unbound keys only** |
+| `orders:read` | External order reads — **bound keys only** |
+| `orders:write` | External order intake — **bound keys only** |
+
+Enforcement stays membership-based, so legacy free-text scopes on existing
+keys remain readable and enforceable — only creation is validated.
+
+## Binding model
+
+The binding is all-or-none and **immutable post-create** (token-shown-once
+lifecycle; rebinding means revoking and issuing a new key). Creation rules,
+validated server-side and mirrored inline in the admin form:
+
+| Rule | Detail |
+| --- | --- |
+| B1 | Any `orders:*` scope ⇒ binding required |
+| B2 | Binding present ⇒ `catalog:write` forbidden (PIM writes stay unbound-only) |
+| B3 | The service Customer Account must be active and belong to the bound Organization |
+| B4 | Organization and Sales Channel must exist (the channel need not be active at creation — the key simply fails closed while it is inactive) |
+| B5 | `expiresAt`, when present, must be a future instant |
+
+At request time a bound key derives a single-org tenant context and a pinned
+sales channel (an explicit `X-Sales-Channel` header naming a different channel
+is refused with `403 API_KEY_CHANNEL_MISMATCH`). An unbound key keeps the
+legacy system context and header/host/default channel resolution.
+
+## Expiry
+
+`expiresAt` is optional and applies to both key modes. Once the instant
+passes, `authenticate` refuses the key with `401 UNAUTHORIZED` — the same
+refusal as a revoked key.
+
+## Entities
+
+`ApiKey` (name, keyHash, lastFour, scopes, status, lastUsedAt, and the
+nullable binding/expiry columns `organizationId`, `salesChannelId`,
+`customerAccountId`, `expiresAt`).
+
+## Out-of-scope / gate behaviour
+
+- Wrong scope ⇒ `403 API_KEY_OUT_OF_SCOPE` + audit row `api_key.out_of_scope`.
+- Unbound key on a bound-only endpoint ⇒ `403 API_KEY_NOT_BOUND` + audit row
+  `api_key.not_bound`.
+- Channel mismatch ⇒ `403 API_KEY_CHANNEL_MISMATCH` + audit row
+  `api_key.channel_mismatch`.
+
+## Extension points
+
+- **New scopes** — extend `apiKeyScopeSchema` in `@endora-commerce/contracts` and gate the
+  new surface at its call site; the service is scope-name-agnostic at
+  enforcement time.
+- **Per-key rate limit** — `api-key-service.authenticate` returns the key
+  id; layer a per-key counter in the pre-handler or a downstream middleware.

package/i18n/en.json

@@ -0,0 +1,5 @@
+{
+  "nav.apiKeys.label": "API keys",
+  "actions.openApiKeys.label": "API keys",
+  "actions.openApiKeys.description": "Machine-to-machine bearer tokens"
+}

package/i18n/pl.json

@@ -0,0 +1,5 @@
+{
+  "nav.apiKeys.label": "Klucze API",
+  "actions.openApiKeys.label": "Klucze API",
+  "actions.openApiKeys.description": "Tokeny bearer dla integracji maszynowych"
+}

package/package.json

@@ -0,0 +1,93 @@
+{
+  "name": "@endora-commerce/mod-api-keys",
+  "version": "0.100.0",
+  "type": "module",
+  "sideEffects": false,
+  "description": "Programmatic API keys (Bearer tokens) used by integrations and webhooks.",
+  "license": "MIT",
+  "endora": {
+    "type": "module",
+    "id": "api_keys"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/endora-commerce/endora-commerce.git",
+    "directory": "packages/modules/api_keys"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/manifest.d.ts",
+      "default": "./dist/manifest.js"
+    },
+    "./backend": {
+      "types": "./dist/backend/index.d.ts",
+      "default": "./dist/backend/index.js"
+    },
+    "./migrations": {
+      "types": "./dist/migrations/index.d.ts",
+      "default": "./dist/migrations/index.js"
+    },
+    "./admin": {
+      "types": "./dist/admin/index.d.ts",
+      "default": "./dist/admin/index.js"
+    },
+    "./tailwind.css": "./tailwind.css",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "i18n",
+    "docs",
+    "tailwind.css"
+  ],
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "peerDependencies": {
+    "@mikro-orm/core": "^6",
+    "@mikro-orm/migrations": "^6",
+    "@mikro-orm/postgresql": "^6",
+    "fastify": "^5",
+    "lucide-react": "^1",
+    "react": "^19",
+    "@endora-commerce/admin-kit": "0.100.0",
+    "@endora-commerce/contracts": "0.100.0",
+    "@endora-commerce/platform": "0.100.0"
+  },
+  "peerDependenciesMeta": {
+    "@endora-commerce/admin-kit": {
+      "optional": true
+    },
+    "lucide-react": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@fastify/type-provider-zod": "^1.0.0",
+    "@mikro-orm/core": "^6.6.13",
+    "@mikro-orm/migrations": "^6.6.13",
+    "@mikro-orm/postgresql": "^6.6.13",
+    "@types/node": "^22.9.0",
+    "@types/react": "^19.2.14",
+    "fastify": "^5.12.5",
+    "lucide-react": "^1.11.0",
+    "react": "^19.2.5",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.11",
+    "@endora-commerce/admin-kit": "0.100.0",
+    "@endora-commerce/contracts": "0.100.0",
+    "@endora-commerce/platform": "0.100.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && tsc -p tsconfig.ui.json",
+    "typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.ui.json --noEmit",
+    "lint": "eslint src",
+    "test": "vitest run"
+  }
+}

package/tailwind.css

@@ -0,0 +1,14 @@
+/* @endora-commerce/mod-api-keys — AUTO-GENERATED by `pnpm --filter backend run manifests:generate`.
+ *
+ * The `@source` directives this package asks its host to scan
+ * (`specs/110-instance-repository/contracts/admin-stylesheet-composition.md` R1).
+ * They resolve relative to **this file**, so they hold wherever the package is
+ * installed — a workspace link here, `node_modules` in a client's instance.
+ *
+ * The `dist` line is what a published tarball ships and is what an instance
+ * scans; the `src` line is inert there and is what keeps `pnpm --filter admin
+ * run dev` reading source in this repository. Do not edit: run
+ * `pnpm --filter backend run manifests:generate`.
+ */
+@source "./dist/admin";
+@source "./src/admin";