@nocobase/app-plugin-api-keys 0.0.0-stage → 1.0.0-beta.14

package/README.md

@@ -1,3 +1,163 @@
-# Temporary Holding Version
+# @nocobase/app-plugin-api-keys
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+API key authentication for NocoBase applications, built on Better Auth.
+
+A key authenticates as the user who created it. `Auth.getSession()` resolves the `x-api-key` header the same way it resolves a session cookie, so `auth.required()`, the route guards, and `@nocobase/app-plugin-authorization` all see the owning user and exactly the roles that user holds. Nothing in an application has to know a request arrived by key rather than by cookie.
+
+Keys are self-service: each signed-in user creates and revokes their own. The plugin ships no page for that; an application builds one on `authClient.apiKey.*` or the scoped key API below and declares it among its own routes.
+
+## What this package is
+
+Better Auth's [API Key plugin](https://www.better-auth.com/docs/plugins/api-key), plus the parts an application needs around it:
+
+- the `apikey` table migration;
+- `apiKey` and `apiKeyClient`, carrying Better Auth's own names and options.
+
+`apiKey` is wrapped only to supply three defaults, all of them overridable; everything else is Better Auth's behavior and its documentation applies unchanged. They come from this package rather than from a dependency each application installs because the migration here has to match the schema that version of `@better-auth/api-key` declares; a test asserts the table carries a column for every field the plugin declares.
+
+## Installing it
+
+```ts
+// server/plugins.ts — migrations for the apikey table
+import apiKeys from '@nocobase/app-plugin-api-keys/server';
+
+// server/config/auth.ts — the Better Auth plugin itself
+import { apiKey } from '@nocobase/app-plugin-api-keys/server';
+
+export default defineAppConfig((_runtime) => ({
+  plugins: [username({ displayUsername: false }), apiKey()],
+}));
+```
+
+```ts
+// client/plugins.ts — registers the plugin; it contributes no pages
+import apiKeys from '@nocobase/app-plugin-api-keys/client';
+apiKeys();
+
+// client/config/auth.ts — so authClient.apiKey.* reaches the endpoints
+import { apiKeyClient } from '@nocobase/app-plugin-api-keys/client';
+
+export default defineAppConfig((_runtime) => ({
+  plugins: [usernameClient({ displayUsername: false }), apiKeyClient()],
+}));
+```
+
+Then run `pnpm nocobase db apply`.
+
+Registering the server plugin without `apiKey()` creates the table and mounts no endpoints; registering `apiKey()` without the server plugin mounts endpoints against a table that does not exist.
+
+## The three defaults
+
+| Option                    | Better Auth                         | Here    | Why                                                                                                                     |
+| ------------------------- | ----------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `enableSessionForAPIKeys` | `false`                             | `true`  | Without it a key authenticates nothing: keys are still issued, and every request carrying one answers 401               |
+| `rateLimit.enabled`       | `true`, 10 requests per key per day | `false` | That is a quota for issuing keys rather than for using them, and it silently breaks the first integration anyone writes |
+| `requireName`             | `false`                             | `true`  | A key is identified by its name, and a key listed as "unnamed" cannot be revoked with any confidence                    |
+
+All three are overridable. `apiKey({ rateLimit: { enabled: true, maxRequests: 1000, timeWindow: 60_000 } })` sets a quota, and passing all three back reproduces Better Auth's own behaviour exactly.
+
+## Using a key
+
+```bash
+curl -H 'x-api-key: <key>' https://example.com/api/orders
+```
+
+## Reading the API document with a key
+
+A valid key may read the application's OpenAPI document and its Swagger UI, exactly as a signed-in session may: `curl -H 'x-api-key: <key>' https://example.com/api/swagger` returns the JSON document, and `/api/swagger/docs` the page. The key is checked the way every other request checks it, so an unknown, expired or disabled key, or one whose owner is disabled, gets `401` with `error.reason` `API_DOCS_UNAUTHENTICATED`, and reading the document extends no session. The document lists this plugin's endpoints under `/api/auth/api-key/...` with the rest of Better Auth's, tagged `Authentication`. A configuration with a `customAPIKeyGetter` is not consulted by this check, because the getter needs a Better Auth endpoint context.
+
+## What a key can do
+
+A key is its owner. Beyond the application's own routes, it reaches the Better Auth endpoints Better Auth lets a session reach — verified against `@better-auth/api-key` 1.7.1 with only an `x-api-key` header:
+
+| Endpoint                                                           |                                                                         |
+| ------------------------------------------------------------------ | ----------------------------------------------------------------------- |
+| `/api-key/*` (create, list, update, delete)                        | 403 `API_KEY_SESSION_FORBIDDEN` — managing keys takes a sign-in         |
+| `POST /update-user`                                                | reachable — profile fields                                              |
+| `GET /list-sessions`                                               | reachable — returns session rows including the unsigned session `token` |
+| `POST /sign-out`                                                   | reachable                                                               |
+| `POST /delete-user`, `POST /change-email`, `POST /revoke-sessions` | 401                                                                     |
+| `POST /change-password`                                            | requires `currentPassword`                                              |
+
+**No key manages keys.** Every `/api-key/*` endpoint refuses a request made with a key, scoped or not, so a leaked key cannot mint its own successors or revoke the evidence; only a signed-in session creates, updates or deletes keys. Routes of the application that manage keys apply the same rule with `requireSignInSession()` after `auth.required()`.
+
+One consequence of an unscoped key reaching the rest is worth planning for. **`/list-sessions` discloses the session token.** It is the unsigned half of the session cookie, which is `token.signature`; replaying it alone does not authenticate, because the HMAC is computed with the auth secret. It becomes a working session takeover only if that secret also leaks or a deployment turns cookie signing off.
+
+An application that wants it closed gives the key a scope, or adds a Better Auth `before` hook of its own.
+
+A rejected key — expired, revoked, or wrong — is answered by a guarded `/api` route with Better Auth's own status in the standard error body, its code as `error.reason` and `authentication` as `error.domain`, so the caller can tell why: `401 KEY_EXPIRED`, `401 KEY_NOT_FOUND`, `429 USAGE_EXCEEDED`. Branch on `error.reason`, never on `message`. `Auth.getSession()` throws Better Auth's `APIError` for a refused key, exactly as Better Auth itself does, and a caller that only asks who is signed in catches it. A disabled user's keys stop working immediately, because `Auth.getSession()` re-reads `user.disabledAt` on every request.
+
+## Scoped keys
+
+A key may carry a scope, as a GitHub fine-grained token does. Its effective permission is its owner's current permission intersected with the scope: the scope never grants anything, and an owner who loses a permission takes it from every key at once. A key without a scope behaves exactly as described above.
+
+The scope is a set of permission groups, each at a level — read, write, or admin, each including the ones before it — and, where a group offers it, limited to some records of a business ("only selected Apps"). Plugins declare their groups as plain data (`KeyScopeGroupDeclaration`, `KeyScopePresetDeclaration` from `@nocobase/app-plugin-api-keys/shared/scopes`, written as literals so the plugin does not depend on this package); the application assembles them, because only it knows every plugin:
+
+```ts
+const scopes = container.resolve(apiKeyScopesToken);
+scopes.mapAccess((ref) => /* page, settings or business access → { resource, action } */);
+scopes.groups.add(RELEASES_KEY_SCOPE_GROUPS[0], releasesKeyScopeObjects(services));
+scopes.presets.add(CI_DEPLOY_PRESET);
+```
+
+A scope is stored in Better Auth's `permissions` column, which Better Auth refuses to take from a client on create or update (`SERVER_ONLY_PROPERTY`), so a key's holder cannot widen it: `{ "$v": ["1"], "releases.apps": ["read", "write"], "releases.apps@": ["app-1"] }`. `/api/apiKeys` offers no way to change a person's key's scope; create another. An application that manages keys of its own (an organization's keys, say) may change one with `ScopedApiKeys.setScope`, deciding itself who may and what they may give. A group the application no longer registers grants nothing, so removing one only narrows the keys that named it.
+
+What enforces a scope on each request:
+
+- Better Auth turns the key into its owner's session, as for any key. This plugin's provider then recognizes the key behind the session (its id and token), reads its scope once per request, and adds it to the authorization identity as `keyScope` (`authz.use`). `authz.can`, `require`, `authorize` and the permissions snapshot deny anything outside it with `KEY_SCOPE`.
+- `auth.required()` refuses a scoped key with 403 `SCOPED_KEY_FORBIDDEN` unless the route opts in with `auth.required({ scopedKeys: true })`. Opt in only where every operation is authorized through `authz`, or where the code narrows by `identity.keyScope` itself; anything that derives permissions on its own (from `permissionSets.getEffective`, say) must intersect with `keyScope` or it widens the key back to its owner.
+- A scoped key reaches no Better Auth account endpoint but `/get-session`: it cannot mint or list keys, change the profile, list sessions or sign out.
+- Record selections are enforced only by the plugin that owns the records, through `keyScope.objects(business)`. An empty selection reaches none of them: the key holds the group's actions, so the commands and routes that need them are offered, while every record the plugin checks is refused.
+
+A service account's key is treated as scoped even without a scope: `required()` refuses it unless the route opts in, it reaches no account endpoint, and its identity carries a `keyScope` that narrows nothing (`permissions: null`), so plugins can tell a key from a person. Disabling the account stops all its keys immediately.
+
+`apiKeys.maxScopedKeyDays` in the application's configuration caps how long a scoped key lives; unset, "never expires" stays available. The editor proposes 90 days.
+
+### Server API
+
+| Export                             | What it is                                                                                                                                                                             |
+| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `apiKeyScopesToken`                | The registry: `groups.add`, `presets.add`, `mapAccess`, `validate`, `compile`                                                                                                          |
+| `scopedApiKeysToken`               | `ScopedApiKeys`: `scopeOptions`, `scopeObjects`, `list`, `get`, `check`, `create`, `issueChecked`, `setScope`, `update`, `rotate`, `revoke`, `revokeAll`, `resolve`, `setOwnKeyPolicy` |
+| `ApiKeyScopeError`                 | A refused scope, 400 with a stable code                                                                                                                                                |
+| `encodeKeyScope`, `decodeKeyScope` | The storage format                                                                                                                                                                     |
+
+`ScopedApiKeys` acts on whichever user it is told; the caller decides who may manage whose keys. An application builds its own key pages and a service account's keys on it.
+
+- `check(input, identity)` validates what `create` would issue — name, description, scope, the records it picks (each must be one `identity` may see) and expiry — without issuing anything, so a caller can refuse before it creates whatever the key belongs to; `issueChecked(userId, checked)` then issues it.
+- `rotate(userId, keyId)` gives a key a new secret in place: the same id, name, description, scope and owner, with the expiry renewed for the lifetime the key had. The old secret stops at once. Better Auth generates and hashes the new value, so its key options apply.
+- `setScope(userId, keyId, scope, identity)` replaces a scoped key's scope; `update(userId, keyId, { name?, description? })` renames it.
+- `setOwnKeyPolicy(policy)` says who may create (and rotate) keys of their own: `(userId) => Promise<boolean>`. Without one everyone may. With one, `POST /api/apiKeys`, its rotation and Better Auth's own `/api-key/create` from a sign-in answer 403 `API_KEY_CREATION_FORBIDDEN` to anyone the policy refuses, while listing and revoking stay open. The plugin's provider connects the Better Auth hook at boot (`connectOwnKeyPolicy`).
+
+### HTTP API
+
+`/api/apiKeys`, for the signed-in person's own keys (a scoped key or a service account is refused with 403 `SCOPED_KEY_FORBIDDEN`, any other key with 403 `API_KEY_SESSION_FORBIDDEN`). Failures answer in the standard error body with domain `apiKeys` and the codes above as `reason`; an invalid body is 400 `INVALID_INPUT` naming the field, and an unknown field is rejected.
+
+| Request                                                 | Answer                                                                                                   |
+| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `GET /scopeOptions`                                     | `{ data }`, `KeyScopeOptions`: the groups with what the caller holds today, presets, expiry, `mayCreate` |
+| `GET /scopeObjects/:group?q=&id=`                       | `{ data, meta: { total } }`: the records the caller may choose for a group; `id` may repeat              |
+| `GET /`                                                 | `{ data, meta: { total } }`: the caller's keys, with scope and last use, never a secret                  |
+| `POST /` `{ name, description?, expiresInDays, scope }` | 201 `{ data: { key, secret } }`, the secret shown once                                                   |
+| `POST /:keyId/rotate`                                   | `{ data: { key, secret } }`: same id, name, scope and lifetime; the old secret stops at once             |
+| `DELETE /:keyId`                                        | 204                                                                                                      |
+
+`toApiKeysApiError(error)` turns `ApiKeyScopeError` and `ApiKeyRequestError` into that body's `ApiError`, for an application's own key routes: `router.onError((error, context) => apiErrorHandler(toApiKeysApiError(error), context))`.
+
+## Verification
+
+```bash
+pnpm --filter @nocobase/app-plugin-api-keys check
+```
+
+## Server extensions
+
+Pass an array to `apiKey()` to configure multiple key classes with unique `configId` values. Each entry receives the usual overridable NocoBase defaults. Set `enableSessionForAPIKeys: false` for keys that an application verifies explicitly instead of resolving into the owner’s Session.
+
+`ApiKeyService` from the server entry binds trusted `create`, `get`, `verify`, `disable`, and `remove` calls to one registered configuration and the Authentication plugin API. It never returns a hash, and creation returns the plaintext once. The service supports database storage only; callers own authorization, the resources they bind keys to, and restrictions on public self-service endpoints. No application-specific scope or App identity is built into this plugin.
+
+Server calls run through `Auth.pluginApi()` and the normal Better Auth hooks; `withConnection(connection)` binds all credential writes to a caller-owned transaction. The added get/delete operations are declared with `createAuthEndpoint.serverOnly` and cannot be reached over HTTP.
+
+`findRequestApiKey(plugin, headers)` returns the key a request carries, read from the headers of every configuration that resolves keys into sessions, and `createApiKeyApiDocsAccess(resolveAuth)` is the API document access check the plugin's server registers; an application assembling its own providers can register it on `apiDocsToken` itself. `Auth.plugin<ApiKeysPlugin>('api-key')?.options.configurations` holds the configurations `apiKey()` was created with, after its defaults.
+
+Trusted lifecycle integrations can call `removeUserApiKeys(connection, userId, configIds)` within their user-deletion transaction to remove database-backed credentials for explicit user-referencing configurations. Do not pass organization-referencing or custom-storage configurations.

package/dist/client/api-keys-client.d.ts

@@ -0,0 +1,19 @@
+import type { ApiKey } from '@better-auth/api-key';
+import type { apiKeyClient } from '@better-auth/api-key/client';
+/**
+ * Better Auth's API Key client plugin, which an application adds to `plugins`
+ * in `client/config/auth.ts` so `authClient.apiKey.*` reaches the endpoints
+ * the server plugin mounts.
+ */
+export { apiKeyClient } from '@better-auth/api-key/client';
+declare module '@nocobase/app-plugin-authentication/client' {
+    interface AuthClientPluginRegistry {
+        'api-key': ReturnType<typeof apiKeyClient>;
+    }
+}
+/**
+ * A key as the list endpoint returns it: Better Auth's own model, minus the
+ * hash the endpoint strips before responding.
+ */
+export type ApiKeySummary = Omit<ApiKey, 'key'>;
+//# sourceMappingURL=api-keys-client.d.ts.map

package/dist/client/api-keys-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-keys-client.d.ts","sourceRoot":"","sources":["../../client/api-keys-client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAIhE;;;;GAIG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAG3D,OAAO,QAAQ,4CAA4C,CAAC;IAC1D,UAAU,wBAAwB;QAChC,SAAS,EAAE,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;KAC5C;CACF;AAED;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC"}

package/dist/client/api-keys-client.js

@@ -0,0 +1,7 @@
+/**
+ * Better Auth's API Key client plugin, which an application adds to `plugins`
+ * in `client/config/auth.ts` so `authClient.apiKey.*` reaches the endpoints
+ * the server plugin mounts.
+ */
+export { apiKeyClient } from '@better-auth/api-key/client';
+//# sourceMappingURL=api-keys-client.js.map

package/dist/client/api-keys-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-keys-client.js","sourceRoot":"","sources":["../../client/api-keys-client.ts"],"names":[],"mappings":"AAKA;;;;GAIG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC"}

package/dist/client/expiry.d.ts

@@ -0,0 +1,23 @@
+import type { ApiKeySummary } from './api-keys-client.js';
+export type ApiKeyExpiryChoice = 'never' | '7' | '30' | '90' | '365';
+/**
+ * The lifetimes the create dialog offers.
+ *
+ * Better Auth measures `expiresIn` in seconds but validates it in whole days
+ * against `keyExpiration.minExpiresIn` and `maxExpiresIn`, which default to 1
+ * and 365. Every choice here stays inside that window, so the dialog cannot
+ * offer a lifetime the server will refuse.
+ */
+export declare const API_KEY_EXPIRY_CHOICES: readonly ApiKeyExpiryChoice[];
+/** Seconds to send as `expiresIn`, or undefined for a key that never expires. */
+export declare function expiryChoiceToSeconds(choice: ApiKeyExpiryChoice): number | undefined;
+/**
+ * The part of a key that is safe to show.
+ *
+ * `start` is the leading characters Better Auth stored at creation, prefix
+ * included. The stored `key` is a hash and is never returned by the list
+ * endpoint, so this is all a listed key can be recognized by.
+ */
+export declare function formatKeyHint(key: Pick<ApiKeySummary, 'prefix' | 'start'>): string;
+export declare function isExpired(expiresAt: string | Date | null | undefined, now?: Date): boolean;
+//# sourceMappingURL=expiry.d.ts.map

package/dist/client/expiry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expiry.d.ts","sourceRoot":"","sources":["../../client/expiry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE1D,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,GAAG,GAAG,IAAI,GAAG,IAAI,GAAG,KAAK,CAAC;AAErE;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,EAAE,SAAS,kBAAkB,EAM/D,CAAC;AAIF,iFAAiF;AACjF,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,kBAAkB,GACzB,MAAM,GAAG,SAAS,CAEpB;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,IAAI,CAAC,aAAa,EAAE,QAAQ,GAAG,OAAO,CAAC,GAC3C,MAAM,CAIR;AAED,wBAAgB,SAAS,CACvB,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,GAAG,SAAS,EAC3C,GAAG,GAAE,IAAiB,GACrB,OAAO,CAGT"}

package/dist/client/expiry.js

@@ -0,0 +1,40 @@
+/**
+ * The lifetimes the create dialog offers.
+ *
+ * Better Auth measures `expiresIn` in seconds but validates it in whole days
+ * against `keyExpiration.minExpiresIn` and `maxExpiresIn`, which default to 1
+ * and 365. Every choice here stays inside that window, so the dialog cannot
+ * offer a lifetime the server will refuse.
+ */
+export const API_KEY_EXPIRY_CHOICES = [
+    'never',
+    '7',
+    '30',
+    '90',
+    '365',
+];
+const SECONDS_PER_DAY = 24 * 60 * 60;
+/** Seconds to send as `expiresIn`, or undefined for a key that never expires. */
+export function expiryChoiceToSeconds(choice) {
+    return choice === 'never' ? undefined : Number(choice) * SECONDS_PER_DAY;
+}
+/**
+ * The part of a key that is safe to show.
+ *
+ * `start` is the leading characters Better Auth stored at creation, prefix
+ * included. The stored `key` is a hash and is never returned by the list
+ * endpoint, so this is all a listed key can be recognized by.
+ */
+export function formatKeyHint(key) {
+    if (key.start)
+        return `${key.start}…`;
+    if (key.prefix)
+        return `${key.prefix}…`;
+    return '—';
+}
+export function isExpired(expiresAt, now = new Date()) {
+    if (!expiresAt)
+        return false;
+    return new Date(expiresAt).getTime() <= now.getTime();
+}
+//# sourceMappingURL=expiry.js.map

package/dist/client/expiry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"expiry.js","sourceRoot":"","sources":["../../client/expiry.ts"],"names":[],"mappings":"AAIA;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAkC;IACnE,OAAO;IACP,GAAG;IACH,IAAI;IACJ,IAAI;IACJ,KAAK;CACN,CAAC;AAEF,MAAM,eAAe,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;AAErC,iFAAiF;AACjF,MAAM,UAAU,qBAAqB,CACnC,MAA0B;IAE1B,OAAO,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,eAAe,CAAC;AAC3E,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAC3B,GAA4C;IAE5C,IAAI,GAAG,CAAC,KAAK;QAAE,OAAO,GAAG,GAAG,CAAC,KAAK,GAAG,CAAC;IACtC,IAAI,GAAG,CAAC,MAAM;QAAE,OAAO,GAAG,GAAG,CAAC,MAAM,GAAG,CAAC;IACxC,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,UAAU,SAAS,CACvB,SAA2C,EAC3C,MAAY,IAAI,IAAI,EAAE;IAEtB,IAAI,CAAC,SAAS;QAAE,OAAO,KAAK,CAAC;IAC7B,OAAO,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;AACxD,CAAC"}

package/dist/client/index.d.ts

@@ -0,0 +1,4 @@
+export { default } from './plugin.js';
+export { apiKeyClient, type ApiKeySummary } from './api-keys-client.js';
+export { API_KEY_EXPIRY_CHOICES, expiryChoiceToSeconds, formatKeyHint, isExpired, type ApiKeyExpiryChoice, } from './expiry.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/client/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../client/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACtC,OAAO,EAAE,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACxE,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,aAAa,EACb,SAAS,EACT,KAAK,kBAAkB,GACxB,MAAM,aAAa,CAAC"}

package/dist/client/index.js

@@ -0,0 +1,6 @@
+// The plugin's public client surface. The default export is the registration
+// factory an application lists in its client/plugins.ts.
+export { default } from './plugin.js';
+export { apiKeyClient } from './api-keys-client.js';
+export { API_KEY_EXPIRY_CHOICES, expiryChoiceToSeconds, formatKeyHint, isExpired, } from './expiry.js';
+//# sourceMappingURL=index.js.map

package/dist/client/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../client/index.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,yDAAyD;AACzD,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACtC,OAAO,EAAE,YAAY,EAAsB,MAAM,sBAAsB,CAAC;AACxE,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,aAAa,EACb,SAAS,GAEV,MAAM,aAAa,CAAC"}

package/dist/client/plugin.d.ts

@@ -0,0 +1,8 @@
+import { type AppClientPluginFactory } from '@nocobase/app-client/plugins';
+/**
+ * Registers the plugin with the client application. It contributes no pages: an application that wants a page for
+ * managing keys builds it on `apiKeyClient` and declares it among its own routes.
+ */
+declare const apiKeys: AppClientPluginFactory;
+export default apiKeys;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/client/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../client/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,sBAAsB,EAC5B,MAAM,8BAA8B,CAAC;AAEtC;;;GAGG;AACH,QAAA,MAAM,OAAO,EAAE,sBAEb,CAAC;AAEH,eAAe,OAAO,CAAC"}

package/dist/client/plugin.js

@@ -0,0 +1,10 @@
+import { defineClientPlugin, } from '@nocobase/app-client/plugins';
+/**
+ * Registers the plugin with the client application. It contributes no pages: an application that wants a page for
+ * managing keys builds it on `apiKeyClient` and declares it among its own routes.
+ */
+const apiKeys = defineClientPlugin({
+    packageName: '@nocobase/app-plugin-api-keys',
+});
+export default apiKeys;
+//# sourceMappingURL=plugin.js.map

package/dist/client/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../../client/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,GAEnB,MAAM,8BAA8B,CAAC;AAEtC;;;GAGG;AACH,MAAM,OAAO,GAA2B,kBAAkB,CAAC;IACzD,WAAW,EAAE,+BAA+B;CAC7C,CAAC,CAAC;AAEH,eAAe,OAAO,CAAC"}

package/dist/database/migrations/.manifest.json

@@ -0,0 +1,9 @@
+{
+  "version": 1,
+  "files": {
+    "202609150001_create_api_key_table.js": {
+      "sourceChecksum": "370b04daffda210c32e8a2931944bcd9e4b19938483d75e02f9fbb525fea72d5",
+      "artifactChecksum": "270d6f8ec497876bff3aa8d304aa6ad51889b5e5ef632a475e8ca797bd80eb86"
+    }
+  }
+}

package/dist/database/migrations/202609150001_create_api_key_table.js

@@ -0,0 +1,58 @@
+import { defineMigration } from '@nocobase/db';
+/**
+ * Creates the table the Better Auth API Key plugin reads and writes.
+ *
+ * The shape is spelled out here rather than derived from the plugin's own
+ * schema, so a later release of `@better-auth/api-key` cannot change what this
+ * migration did. When that schema gains a field, add it in a new migration.
+ *
+ * The duration fields are milliseconds held in a 32-bit integer, which caps a
+ * refill interval or rate-limit window at roughly 24 days. That is well past
+ * the one-day default and keeps every dialect returning a number; a longer
+ * window needs a widening migration rather than a value that silently wraps.
+ */
+const migration = defineMigration({
+    name: '202609150001_create_api_key_table',
+    async up({ builder }) {
+        await builder.createCollection('apikey', (collection) => {
+            collection.string('id', { length: 64 }).notNull();
+            collection
+                .string('configId', { length: 128 })
+                .notNull()
+                .defaultTo('default');
+            collection.string('name', { length: 255 }).nullable();
+            collection.string('prefix', { length: 64 }).nullable();
+            // The first few characters, shown in the UI so a listed key is
+            // recognizable. `key` itself is a hash and is never displayed.
+            collection.string('start', { length: 64 }).nullable();
+            collection.string('key', { length: 255 }).notNull();
+            collection.string('referenceId', { length: 64 }).notNull();
+            collection.integer('refillInterval').nullable();
+            collection.integer('refillAmount').nullable();
+            collection.datetime('lastRefillAt').nullable();
+            collection.boolean('enabled').notNull().defaultTo(true);
+            collection.boolean('rateLimitEnabled').notNull().defaultTo(true);
+            collection.integer('rateLimitTimeWindow').nullable();
+            collection.integer('rateLimitMax').nullable();
+            collection.integer('requestCount').notNull().defaultTo(0);
+            collection.integer('remaining').nullable();
+            collection.datetime('lastRequest').nullable();
+            collection.datetime('expiresAt').nullable();
+            collection.datetime('createdAt').notNull();
+            collection.datetime('updatedAt').notNull();
+            collection.text('permissions').nullable();
+            collection.text('metadata').nullable();
+            collection.primary('id', { name: 'pk_apikey' });
+            collection.index('key', { name: 'idx_apikey_key' });
+            collection.index('referenceId', { name: 'idx_apikey_reference' });
+            collection.index('configId', { name: 'idx_apikey_config' });
+            collection.index('expiresAt', { name: 'idx_apikey_expires_at' });
+        });
+    },
+    async down({ builder }) {
+        await builder.dropCollection('apikey');
+    },
+});
+export default migration;
+//# sourceMappingURL=202609150001_create_api_key_table.js.map
+// @nocobase/task-manifest v1

package/dist/database/migrations/202609150001_create_api_key_table.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"202609150001_create_api_key_table.js","sourceRoot":"","sources":["../../../database/migrations/202609150001_create_api_key_table.ts"],"names":[],"mappings":"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"}

package/dist/server/api-docs.d.ts

@@ -0,0 +1,24 @@
+import type { Auth } from '@nocobase/app-plugin-authentication/server';
+import type { ApiDocsAccess, ApiDocumentFragment } from '@nocobase/app-server/router';
+/** The security scheme an API key satisfies, in `components.securitySchemes`. */
+export declare const API_KEY_SECURITY_SCHEME = "apiKeyAuth";
+/**
+ * Lets a request carrying a valid API key read the API documentation. The key is checked exactly as for any other
+ * request — Better Auth resolves it to its owner's session, which refuses a disabled, expired or unknown key and a key
+ * whose owner is disabled — but without extending a session, so reading the documentation changes no state.
+ *
+ * Allows nothing when the application has not configured this package's `apiKey()` Better Auth plugin, or when the
+ * request carries no key in the headers that plugin reads.
+ */
+export declare function createApiKeyApiDocsAccess(resolveAuth: () => Pick<Auth, 'getSession' | 'plugin'>): ApiDocsAccess;
+/**
+ * The API key header as the document's security scheme, `apiKeyAuth`, and a top-level requirement naming it, offered
+ * beside the session cookie's: a request carrying either is authenticated. The header is the first one this package's
+ * `apiKey()` Better Auth plugin reads a key from, `x-api-key` unless configured. Swagger UI's "Authorize" takes the key
+ * and sends it in that header.
+ *
+ * Contributes nothing when the application has not configured the `apiKey()` plugin, or when no configuration turns
+ * keys into sessions through a header, because then no request authenticates with a key.
+ */
+export declare function createApiKeySecurityFragment(resolveAuth: () => Pick<Auth, 'plugin'>): ApiDocumentFragment;
+//# sourceMappingURL=api-docs.d.ts.map

package/dist/server/api-docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-docs.d.ts","sourceRoot":"","sources":["../../server/api-docs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,4CAA4C,CAAC;AACvE,OAAO,KAAK,EACV,aAAa,EACb,mBAAmB,EACpB,MAAM,6BAA6B,CAAC;AAWrC,iFAAiF;AACjF,eAAO,MAAM,uBAAuB,eAAe,CAAC;AAEpD;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CACvC,WAAW,EAAE,MAAM,IAAI,CAAC,IAAI,EAAE,YAAY,GAAG,QAAQ,CAAC,GACrD,aAAa,CAsBf;AAED;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAC1C,WAAW,EAAE,MAAM,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,GACtC,mBAAmB,CAqBrB"}

package/dist/server/api-docs.js

@@ -0,0 +1,73 @@
+import { APIError } from 'better-auth/api';
+import { findRequestApiKey, requestApiKeyHeaders, } from './api-keys.js';
+const PACKAGE_NAME = '@nocobase/app-plugin-api-keys';
+/** The security scheme an API key satisfies, in `components.securitySchemes`. */
+export const API_KEY_SECURITY_SCHEME = 'apiKeyAuth';
+/**
+ * Lets a request carrying a valid API key read the API documentation. The key is checked exactly as for any other
+ * request — Better Auth resolves it to its owner's session, which refuses a disabled, expired or unknown key and a key
+ * whose owner is disabled — but without extending a session, so reading the documentation changes no state.
+ *
+ * Allows nothing when the application has not configured this package's `apiKey()` Better Auth plugin, or when the
+ * request carries no key in the headers that plugin reads.
+ */
+export function createApiKeyApiDocsAccess(resolveAuth) {
+    return {
+        name: PACKAGE_NAME,
+        check: async (context) => {
+            const auth = resolveAuth();
+            const plugin = auth.plugin('api-key');
+            if (!plugin?.options?.configurations)
+                return false;
+            const headers = context.req.raw.headers;
+            const key = findRequestApiKey(plugin, headers);
+            if (!key)
+                return false;
+            try {
+                const session = await auth.getSession(headers, {
+                    disableRefresh: true,
+                });
+                // Better Auth answers a request carrying a key with the key's session, whose token is the key itself.
+                return session?.session.token === key;
+            }
+            catch (error) {
+                if (error instanceof APIError)
+                    return false;
+                throw error;
+            }
+        },
+    };
+}
+/**
+ * The API key header as the document's security scheme, `apiKeyAuth`, and a top-level requirement naming it, offered
+ * beside the session cookie's: a request carrying either is authenticated. The header is the first one this package's
+ * `apiKey()` Better Auth plugin reads a key from, `x-api-key` unless configured. Swagger UI's "Authorize" takes the key
+ * and sends it in that header.
+ *
+ * Contributes nothing when the application has not configured the `apiKey()` plugin, or when no configuration turns
+ * keys into sessions through a header, because then no request authenticates with a key.
+ */
+export function createApiKeySecurityFragment(resolveAuth) {
+    const plugin = resolveAuth().plugin('api-key');
+    const [header, ...alternatives] = plugin?.options?.configurations
+        ? requestApiKeyHeaders(plugin)
+        : [];
+    if (!header)
+        return { owner: PACKAGE_NAME };
+    return {
+        owner: PACKAGE_NAME,
+        namespace: 'apiKeys',
+        components: {
+            securitySchemes: {
+                [API_KEY_SECURITY_SCHEME]: {
+                    type: 'apiKey',
+                    in: 'header',
+                    name: header,
+                    description: `An API key issued on the API keys settings page or through \`/api/auth/api-key/create\`. It acts as the user who owns it.${alternatives.length > 0 ? ` The ${alternatives.map((name) => `\`${name}\``).join(', ')} header${alternatives.length > 1 ? 's carry' : ' carries'} it as well.` : ''}`,
+                },
+            },
+        },
+        security: [{ [API_KEY_SECURITY_SCHEME]: [] }],
+    };
+}
+//# sourceMappingURL=api-docs.js.map

package/dist/server/api-docs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-docs.js","sourceRoot":"","sources":["../../server/api-docs.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAE3C,OAAO,EACL,iBAAiB,EACjB,oBAAoB,GAErB,MAAM,eAAe,CAAC;AAEvB,MAAM,YAAY,GAAG,+BAA+B,CAAC;AAErD,iFAAiF;AACjF,MAAM,CAAC,MAAM,uBAAuB,GAAG,YAAY,CAAC;AAEpD;;;;;;;GAOG;AACH,MAAM,UAAU,yBAAyB,CACvC,WAAsD;IAEtD,OAAO;QACL,IAAI,EAAE,YAAY;QAClB,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;YACvB,MAAM,IAAI,GAAG,WAAW,EAAE,CAAC;YAC3B,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAgB,SAAS,CAAC,CAAC;YACrD,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,cAAc;gBAAE,OAAO,KAAK,CAAC;YACnD,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC;YACxC,MAAM,GAAG,GAAG,iBAAiB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;YAC/C,IAAI,CAAC,GAAG;gBAAE,OAAO,KAAK,CAAC;YACvB,IAAI,CAAC;gBACH,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,OAAO,EAAE;oBAC7C,cAAc,EAAE,IAAI;iBACrB,CAAC,CAAC;gBACH,sGAAsG;gBACtG,OAAO,OAAO,EAAE,OAAO,CAAC,KAAK,KAAK,GAAG,CAAC;YACxC,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,IAAI,KAAK,YAAY,QAAQ;oBAAE,OAAO,KAAK,CAAC;gBAC5C,MAAM,KAAK,CAAC;YACd,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,4BAA4B,CAC1C,WAAuC;IAEvC,MAAM,MAAM,GAAG,WAAW,EAAE,CAAC,MAAM,CAAgB,SAAS,CAAC,CAAC;IAC9D,MAAM,CAAC,MAAM,EAAE,GAAG,YAAY,CAAC,GAAG,MAAM,EAAE,OAAO,EAAE,cAAc;QAC/D,CAAC,CAAC,oBAAoB,CAAC,MAAM,CAAC;QAC9B,CAAC,CAAC,EAAE,CAAC;IACP,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,CAAC;IAC5C,OAAO;QACL,KAAK,EAAE,YAAY;QACnB,SAAS,EAAE,SAAS;QACpB,UAAU,EAAE;YACV,eAAe,EAAE;gBACf,CAAC,uBAAuB,CAAC,EAAE;oBACzB,IAAI,EAAE,QAAQ;oBACd,EAAE,EAAE,QAAQ;oBACZ,IAAI,EAAE,MAAM;oBACZ,WAAW,EAAE,4HAA4H,YAAY,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,YAAY,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,YAAY,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,cAAc,CAAC,CAAC,CAAC,EAAE,EAAE;iBAC/S;aACF;SACF;QACD,QAAQ,EAAE,CAAC,EAAE,CAAC,uBAAuB,CAAC,EAAE,EAAE,EAAE,CAAC;KAC9C,CAAC;AACJ,CAAC"}

package/dist/server/api-keys.d.ts

@@ -0,0 +1,52 @@
+import { apiKey as betterAuthApiKey, type ApiKeyConfigurationOptions } from '@better-auth/api-key';
+import { createAuthEndpoint } from 'better-auth/api';
+import type { ApiKey } from '@better-auth/api-key';
+type ServerEndpoint<Options extends Parameters<typeof createAuthEndpoint.serverOnly>[0], Result> = ReturnType<typeof createAuthEndpoint.serverOnly<string, Options, Result>>;
+type UpstreamPlugin = ReturnType<typeof betterAuthApiKey>;
+type ManagedQuery = ReturnType<UpstreamPlugin['endpoints']['getApiKey']['options']['query']['partial']>;
+type ManagedBody = UpstreamPlugin['endpoints']['deleteApiKey']['options']['body'];
+/** The configurations the plugin was created with, after this package's defaults are applied. */
+export interface ApiKeysPluginOptions {
+    readonly configurations: readonly ApiKeyConfigurationOptions[];
+}
+export type ApiKeysPlugin = Omit<UpstreamPlugin, 'endpoints'> & {
+    /** Read by this package's server, for instance to find the key a request carries; Better Auth ignores it. */
+    options: ApiKeysPluginOptions;
+    endpoints: UpstreamPlugin['endpoints'] & {
+        getServerApiKey: ServerEndpoint<{
+            method: 'GET';
+            query: ManagedQuery;
+        }, Omit<ApiKey, 'key'> | null>;
+        deleteServerApiKey: ServerEndpoint<{
+            method: 'POST';
+            body: ManagedBody;
+        }, {
+            success: boolean;
+        }>;
+    };
+};
+/**
+ * Where the plugin's provider puts the application's own-key policy (`ScopedApiKeys.setOwnKeyPolicy`), so the hook on
+ * Better Auth's own `/api-key/create` asks the same question `/api/apiKeys` does.
+ */
+export declare const OWN_KEY_POLICY_SLOT: unique symbol;
+export interface OwnKeyPolicySlot {
+    current: ((userId: string) => Promise<boolean>) | null;
+}
+/** The slot of a plugin `apiKey()` made, or undefined for any other plugin. */
+export declare function ownKeyPolicySlotOf(plugin: unknown): OwnKeyPolicySlot | undefined;
+/**
+ * The API key a request carries, read the way the plugin reads it to authenticate a request: from the header each
+ * configuration that turns keys into sessions names, `x-api-key` unless configured. A configuration with a
+ * `customAPIKeyGetter` is skipped, because that getter needs a Better Auth endpoint context this caller does not have.
+ */
+export declare function findRequestApiKey(plugin: Pick<ApiKeysPlugin, 'options'>, headers: Headers): string | undefined;
+/**
+ * The headers a request may carry its API key in, in the order `findRequestApiKey` reads them: those of each
+ * configuration that turns keys into sessions, `x-api-key` unless configured, without one that has a
+ * `customAPIKeyGetter`.
+ */
+export declare function requestApiKeyHeaders(plugin: Pick<ApiKeysPlugin, 'options'>): string[];
+export declare function apiKey(options?: ApiKeyConfigurationOptions | ApiKeyConfigurationOptions[]): ApiKeysPlugin;
+export {};
+//# sourceMappingURL=api-keys.d.ts.map

package/dist/server/api-keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-keys.d.ts","sourceRoot":"","sources":["../../server/api-keys.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,MAAM,IAAI,gBAAgB,EAC1B,KAAK,0BAA0B,EAChC,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAEL,kBAAkB,EAGnB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAGnD,KAAK,cAAc,CACjB,OAAO,SAAS,UAAU,CAAC,OAAO,kBAAkB,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,EACnE,MAAM,IACJ,UAAU,CAAC,OAAO,kBAAkB,CAAC,UAAU,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC;AAE9E,KAAK,cAAc,GAAG,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAC1D,KAAK,YAAY,GAAG,UAAU,CAC5B,cAAc,CAAC,WAAW,CAAC,CAAC,WAAW,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC,CAAC,SAAS,CAAC,CACxE,CAAC;AACF,KAAK,WAAW,GACd,cAAc,CAAC,WAAW,CAAC,CAAC,cAAc,CAAC,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC;AACjE,iGAAiG;AACjG,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,cAAc,EAAE,SAAS,0BAA0B,EAAE,CAAC;CAChE;AAED,MAAM,MAAM,aAAa,GAAG,IAAI,CAAC,cAAc,EAAE,WAAW,CAAC,GAAG;IAC9D,6GAA6G;IAC7G,OAAO,EAAE,oBAAoB,CAAC;IAC9B,SAAS,EAAE,cAAc,CAAC,WAAW,CAAC,GAAG;QACvC,eAAe,EAAE,cAAc,CAC7B;YAAE,MAAM,EAAE,KAAK,CAAC;YAAC,KAAK,EAAE,YAAY,CAAA;SAAE,EACtC,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,IAAI,CAC3B,CAAC;QACF,kBAAkB,EAAE,cAAc,CAChC;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,WAAW,CAAA;SAAE,EACrC;YAAE,OAAO,EAAE,OAAO,CAAA;SAAE,CACrB,CAAC;KACH,CAAC;CACH,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,mBAAmB,EAAE,OAAO,MAExC,CAAC;AAEF,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;CACxD;AAED,+EAA+E;AAC/E,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,OAAO,GACd,gBAAgB,GAAG,SAAS,CAI9B;AA+KD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,IAAI,CAAC,aAAa,EAAE,SAAS,CAAC,EACtC,OAAO,EAAE,OAAO,GACf,MAAM,GAAG,SAAS,CAMpB;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,IAAI,CAAC,aAAa,EAAE,SAAS,CAAC,GACrC,MAAM,EAAE,CAUV;AAED,wBAAgB,MAAM,CACpB,OAAO,GAAE,0BAA0B,GAAG,0BAA0B,EAAO,GACtE,aAAa,CAEf"}