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

package/dist/server/scopes.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The key-scope registry: the permission groups and presets an application assembles from its plugins, how each
+ * `AccessRef` maps to an authorization resource and action, and how a stored scope becomes the `KeyScope` the
+ * authorization core enforces. Plugins never import this; the application hands their declarations to it.
+ */
+import type { AuthorizationIdentity, KeyScope, ResourceRef } from '@nocobase/authorization/core';
+import { type ServiceToken } from '@nocobase/service-provider';
+import { type AccessRef, type KeyScopeGroupDeclaration, type KeyScopeInput, type KeyScopeLevel, type KeyScopeObject, type KeyScopePresetDeclaration } from '../shared/scopes.js';
+/** Lists the records a group may be limited to: only those the identity may see in that business. */
+export interface KeyScopeObjectSource {
+    list(input: {
+        readonly identity: AuthorizationIdentity;
+        readonly search?: string;
+        readonly ids?: readonly string[];
+    }): Promise<readonly KeyScopeObject[]>;
+}
+/**
+ * What an `AccessRef` is checked as: one action of a resource, or several where holding any of them is holding the ref
+ * (a business action granted once per level, `edit.related` and `edit.all`); a scope covering the ref allows every one.
+ * Null when the application does not offer it.
+ */
+export type AccessMapping = (ref: AccessRef) => {
+    readonly resource: ResourceRef;
+    readonly action: string;
+} | {
+    readonly resource: ResourceRef;
+    readonly actions: readonly string[];
+} | null;
+/** A mapped `AccessRef`: the actions of a resource it stands for, any one of which is holding it. */
+export interface MappedAccess {
+    readonly resource: ResourceRef;
+    readonly actions: readonly string[];
+}
+/** A refused scope: 400 with a stable code. */
+export declare class ApiKeyScopeError extends Error {
+    readonly code: 'INVALID_SCOPE' | 'EMPTY_SCOPE' | 'UNKNOWN_SCOPE_GROUP' | 'SCOPE_LEVEL_NOT_OFFERED' | 'SCOPE_OBJECTS_NOT_OFFERED' | 'UNKNOWN_SCOPE_OBJECT';
+    constructor(code: 'INVALID_SCOPE' | 'EMPTY_SCOPE' | 'UNKNOWN_SCOPE_GROUP' | 'SCOPE_LEVEL_NOT_OFFERED' | 'SCOPE_OBJECTS_NOT_OFFERED' | 'UNKNOWN_SCOPE_OBJECT', message: string);
+}
+export interface ApiKeyScopes {
+    readonly groups: {
+        /** Registers a group, with the source of its records when it offers object selection. Returns its removal. */
+        add(group: KeyScopeGroupDeclaration, objects?: KeyScopeObjectSource): () => void;
+        list(): readonly KeyScopeGroupDeclaration[];
+        get(id: string): KeyScopeGroupDeclaration | undefined;
+        /** The record source of a group that offers object selection. */
+        objects(id: string): KeyScopeObjectSource | undefined;
+    };
+    readonly presets: {
+        add(preset: KeyScopePresetDeclaration): () => void;
+        list(): readonly KeyScopePresetDeclaration[];
+    };
+    /**
+     * Sets how an `AccessRef` is checked. The default maps a page to `page:<id>/access` and a settings action to
+     * `settings:<id>/<action>`, and offers no business action, whose resource type only the application knows.
+     */
+    mapAccess(mapping: AccessMapping): void;
+    /** The resource actions a level of a group covers, mapped; refs the application does not offer are left out. */
+    accessOf(group: KeyScopeGroupDeclaration, level: KeyScopeLevel, options?: {
+        readonly allObjects?: boolean;
+    }): MappedAccess[];
+    /** Checks a scope against the registered groups; throws `ApiKeyScopeError`. Record ids are checked by the caller. */
+    validate(input: unknown): KeyScopeInput;
+    /** The `KeyScope` of a stored scope. Groups no longer registered grant nothing, so a removed group only narrows. */
+    compile(keyId: string, scope: KeyScopeInput): KeyScope;
+    /** The `KeyScope` of a key bounded only by its owner (a service account's unscoped key): it narrows nothing. */
+    unbounded(keyId: string): KeyScope;
+}
+export declare const apiKeyScopesToken: ServiceToken<ApiKeyScopes>;
+export declare function createApiKeyScopes(): ApiKeyScopes;
+//# sourceMappingURL=scopes.d.ts.map

package/dist/server/scopes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scopes.d.ts","sourceRoot":"","sources":["../../server/scopes.ts"],"names":[],"mappings":"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"}

package/dist/server/scopes.js

@@ -0,0 +1,165 @@
+import { createServiceToken, } from '@nocobase/service-provider';
+import { KEY_SCOPE_LEVELS, levelsUpTo, pickedObjects, } from '../shared/scopes.js';
+/** A refused scope: 400 with a stable code. */
+export class ApiKeyScopeError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'ApiKeyScopeError';
+    }
+}
+export const apiKeyScopesToken = createServiceToken('@nocobase/app-plugin-api-keys/scopes');
+const defaultMapping = (ref) => {
+    if (ref.kind === 'page')
+        return { resource: { type: 'page', id: ref.id }, action: 'access' };
+    if (ref.kind === 'settings')
+        return { resource: { type: 'settings', id: ref.id }, action: ref.action };
+    return null;
+};
+const refKey = (ref) => ref.kind === 'page'
+    ? `page:${ref.id}`
+    : `${ref.kind}:${ref.id}/${ref.action}`;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function createApiKeyScopes() {
+    const groups = new Map();
+    const presets = new Map();
+    let mapping = defaultMapping;
+    const offered = (group) => KEY_SCOPE_LEVELS.filter((level) => group.levels[level] !== undefined);
+    const accessOf = (group, level, options = {}) => {
+        const unscopedOnly = new Set((group.objects?.allowsUnscoped ?? []).map(refKey));
+        const result = [];
+        for (const step of levelsUpTo(level))
+            for (const ref of group.levels[step] ?? []) {
+                if (options.allObjects === false && unscopedOnly.has(refKey(ref)))
+                    continue;
+                const mapped = mapping(ref);
+                if (mapped)
+                    result.push({
+                        resource: mapped.resource,
+                        actions: 'actions' in mapped ? mapped.actions : [mapped.action],
+                    });
+            }
+        return result;
+    };
+    function validateGrant(id, value) {
+        const group = groups.get(id)?.group;
+        if (!group)
+            throw new ApiKeyScopeError('UNKNOWN_SCOPE_GROUP', `${id} is not a permission group.`);
+        if (!isRecord(value) || typeof value.level !== 'string')
+            throw new ApiKeyScopeError('INVALID_SCOPE', `${id} must be { level, objects? }.`);
+        const level = value.level;
+        if (!offered(group).includes(level))
+            throw new ApiKeyScopeError('SCOPE_LEVEL_NOT_OFFERED', `${id} offers ${offered(group).join(', ')}, not ${String(value.level)}.`);
+        const objects = value.objects;
+        if (objects === undefined || objects === 'all')
+            return { level };
+        if (!group.objects)
+            throw new ApiKeyScopeError('SCOPE_OBJECTS_NOT_OFFERED', `${id} cannot be limited to some records.`);
+        // An empty list reaches none of the records: the group's actions with nothing to act on, such as a key an
+        // application recognizes by its identity for records it does not have yet.
+        if (!Array.isArray(objects) ||
+            objects.some((item) => typeof item !== 'string' || !item.trim()))
+            throw new ApiKeyScopeError('INVALID_SCOPE', `${id}.objects must be "all" or a list of ids.`);
+        return { level, objects: [...new Set(objects)] };
+    }
+    function scopeOf(keyId, entries, objects) {
+        const key = (resource) => JSON.stringify([resource.type, resource.id]);
+        const resources = new Map();
+        for (const [entry] of entries) {
+            const [type, id] = JSON.parse(entry);
+            resources.set(entry, { type, id });
+        }
+        return {
+            keyId,
+            allows: (resource, action) => entries.get(key(resource))?.has(action) ?? false,
+            objects: (business) => objects.get(business) ?? 'all',
+            permissions: [...entries].map(([entry, actions]) => ({
+                resource: resources.get(entry),
+                actions: [...actions].sort(),
+            })),
+        };
+    }
+    return {
+        groups: {
+            add(group, objects) {
+                if (groups.has(group.id))
+                    throw new Error(`Permission group ${group.id} is registered already.`);
+                if (group.objects) {
+                    const business = group.objects.business;
+                    for (const existing of groups.values())
+                        if (existing.group.objects?.business === business)
+                            throw new Error(`Permission groups ${existing.group.id} and ${group.id} both select records of ${business}.`);
+                }
+                if (offered(group).length === 0)
+                    throw new Error(`Permission group ${group.id} offers no level.`);
+                const entry = { group, ...(objects ? { objects } : {}) };
+                groups.set(group.id, entry);
+                return () => {
+                    if (groups.get(group.id) === entry)
+                        groups.delete(group.id);
+                };
+            },
+            list: () => [...groups.values()].map((entry) => entry.group),
+            get: (id) => groups.get(id)?.group,
+            objects: (id) => groups.get(id)?.objects,
+        },
+        presets: {
+            add(preset) {
+                if (presets.has(preset.id))
+                    throw new Error(`Key scope preset ${preset.id} is registered already.`);
+                presets.set(preset.id, preset);
+                return () => {
+                    if (presets.get(preset.id) === preset)
+                        presets.delete(preset.id);
+                };
+            },
+            list: () => [...presets.values()],
+        },
+        mapAccess(next) {
+            mapping = next;
+        },
+        accessOf,
+        validate(input) {
+            if (!isRecord(input) || !isRecord(input.groups))
+                throw new ApiKeyScopeError('INVALID_SCOPE', 'A scope is { groups: { <group>: { level, objects? } } }.');
+            const result = {};
+            for (const [id, value] of Object.entries(input.groups))
+                result[id] = validateGrant(id, value);
+            if (Object.keys(result).length === 0)
+                throw new ApiKeyScopeError('EMPTY_SCOPE', 'A scoped key needs at least one permission.');
+            return { groups: result };
+        },
+        compile(keyId, scope) {
+            const entries = new Map();
+            const objects = new Map();
+            for (const [id, grant] of Object.entries(scope.groups)) {
+                const group = groups.get(id)?.group;
+                if (!group || !offered(group).includes(grant.level))
+                    continue;
+                const picked = group.objects ? pickedObjects(grant) : undefined;
+                if (picked && group.objects)
+                    objects.set(group.objects.business, picked);
+                for (const { resource, actions: mapped } of accessOf(group, grant.level, { allObjects: picked === undefined })) {
+                    const key = JSON.stringify([resource.type, resource.id]);
+                    const actions = entries.get(key) ?? new Set();
+                    for (const action of mapped)
+                        actions.add(action);
+                    entries.set(key, actions);
+                }
+            }
+            return scopeOf(keyId, entries, objects);
+        },
+        unbounded(keyId) {
+            return {
+                keyId,
+                allows: () => true,
+                objects: () => 'all',
+                permissions: null,
+            };
+        },
+    };
+}
+//# sourceMappingURL=scopes.js.map

package/dist/server/scopes.js.map

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

package/dist/server/service.d.ts

@@ -0,0 +1,28 @@
+import type { ApiKey } from '@better-auth/api-key';
+import type { Auth } from '@nocobase/app-plugin-authentication/server';
+import type { DatabaseConnection } from '@nocobase/db';
+export type ServerApiKeySummary = Omit<ApiKey, 'key'>;
+export interface CreateServerApiKeyInput {
+    readonly userId: string;
+    readonly name: string;
+    readonly expiresIn?: number | null;
+}
+/** Trusted, database-backed operations. Callers must enforce their own authorization. */
+export declare class ApiKeyService {
+    private readonly auth;
+    private readonly configId;
+    constructor(auth: Pick<Auth, 'pluginApi' | 'forConnection'>, configId: string);
+    withConnection(connection: DatabaseConnection): ApiKeyService;
+    private runtime;
+    create(input: CreateServerApiKeyInput): Promise<{
+        key: ServerApiKeySummary;
+        secret: string;
+    }>;
+    verify(secret: string): Promise<ServerApiKeySummary | null>;
+    get(id: string): Promise<ServerApiKeySummary | null>;
+    disable(id: string): Promise<void>;
+    remove(id: string): Promise<void>;
+}
+/** Remove database-backed user credentials in the caller's deletion transaction. */
+export declare function removeUserApiKeys(connection: DatabaseConnection, userId: string, configIds: readonly string[]): Promise<void>;
+//# sourceMappingURL=service.d.ts.map

package/dist/server/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../server/service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,4CAA4C,CAAC;AAEvE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAEvD,MAAM,MAAM,mBAAmB,GAAG,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AACtD,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC;AAED,yFAAyF;AACzF,qBAAa,aAAa;IAEtB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBADR,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,WAAW,GAAG,eAAe,CAAC,EAC/C,QAAQ,EAAE,MAAM;IAGnC,cAAc,CAAC,UAAU,EAAE,kBAAkB,GAAG,aAAa;YAO/C,OAAO;IAOf,MAAM,CACV,KAAK,EAAE,uBAAuB,GAC7B,OAAO,CAAC;QAAE,GAAG,EAAE,mBAAmB,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAQlD,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC;IAQ3D,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC;IAOpD,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAclC,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAMxC;AAED,oFAAoF;AACpF,wBAAsB,iBAAiB,CACrC,UAAU,EAAE,kBAAkB,EAC9B,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,OAAO,CAAC,IAAI,CAAC,CAOf"}

package/dist/server/service.js

@@ -0,0 +1,69 @@
+/** Trusted, database-backed operations. Callers must enforce their own authorization. */
+export class ApiKeyService {
+    auth;
+    configId;
+    constructor(auth, configId) {
+        this.auth = auth;
+        this.configId = configId;
+    }
+    withConnection(connection) {
+        return new ApiKeyService(this.auth.forConnection(connection), this.configId);
+    }
+    async runtime() {
+        const endpoints = this.auth.pluginApi('api-key');
+        // Validate the configuration rather than accepting Better Auth's fallback to default.
+        await endpoints.getServerApiKey({ query: { configId: this.configId } });
+        return endpoints;
+    }
+    async create(input) {
+        const endpoints = await this.runtime();
+        const { key: secret, ...key } = await endpoints.createApiKey({
+            body: { ...input, configId: this.configId },
+        });
+        return { key, secret };
+    }
+    async verify(secret) {
+        const endpoints = await this.runtime();
+        const result = await endpoints.verifyApiKey({
+            body: { configId: this.configId, key: secret },
+        });
+        return result.valid ? result.key : null;
+    }
+    async get(id) {
+        const endpoints = await this.runtime();
+        return endpoints.getServerApiKey({
+            query: { id, configId: this.configId },
+        });
+    }
+    async disable(id) {
+        const key = await this.get(id);
+        if (!key || !key.enabled)
+            return;
+        const endpoints = await this.runtime();
+        await endpoints.updateApiKey({
+            body: {
+                configId: this.configId,
+                keyId: id,
+                userId: key.referenceId,
+                enabled: false,
+            },
+        });
+    }
+    async remove(id) {
+        const endpoints = await this.runtime();
+        await endpoints.deleteServerApiKey({
+            body: { keyId: id, configId: this.configId },
+        });
+    }
+}
+/** Remove database-backed user credentials in the caller's deletion transaction. */
+export async function removeUserApiKeys(connection, userId, configIds) {
+    if (!configIds.length)
+        return;
+    await connection.query
+        .deleteFrom('apikey')
+        .where('referenceId', '=', userId)
+        .where('configId', 'in', [...configIds])
+        .execute();
+}
+//# sourceMappingURL=service.js.map

package/dist/server/service.js.map

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

package/dist/server/tokens.d.ts

@@ -0,0 +1,6 @@
+import { type ServiceToken } from '@nocobase/service-provider';
+import type { ScopedApiKeys } from './scoped-keys.js';
+export { apiKeyScopesToken } from './scopes.js';
+/** Keys with scopes for any user: what an application builds key pages and service-account keys on. */
+export declare const scopedApiKeysToken: ServiceToken<ScopedApiKeys>;
+//# sourceMappingURL=tokens.d.ts.map

package/dist/server/tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../server/tokens.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,YAAY,EAClB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEhD,uGAAuG;AACvG,eAAO,MAAM,kBAAkB,EAAE,YAAY,CAAC,aAAa,CAGxD,CAAC"}

package/dist/server/tokens.js

@@ -0,0 +1,5 @@
+import { createServiceToken, } from '@nocobase/service-provider';
+export { apiKeyScopesToken } from './scopes.js';
+/** Keys with scopes for any user: what an application builds key pages and service-account keys on. */
+export const scopedApiKeysToken = createServiceToken('@nocobase/app-plugin-api-keys/scoped-keys');
+//# sourceMappingURL=tokens.js.map

package/dist/server/tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../../server/tokens.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,GAEnB,MAAM,4BAA4B,CAAC;AAIpC,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEhD,uGAAuG;AACvG,MAAM,CAAC,MAAM,kBAAkB,GAC7B,kBAAkB,CAChB,2CAA2C,CAC5C,CAAC"}

package/dist/shared/scopes.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Key scopes as data: what a plugin declares it offers (permission groups and presets), what a key's scope holds, and
+ * how a scope is stored in Better Auth's `permissions` column. Nothing here imports another plugin, so a plugin that
+ * contributes a group writes a literal of the same shape without depending on this package.
+ *
+ * A scope only ever narrows: a key's effective permission is its owner's current permission intersected with the
+ * scope. A key without a scope (`permissions = null`) is its owner, exactly as before scopes existed.
+ */
+/** A level of a group; each includes the ones before it. */
+export type KeyScopeLevel = 'read' | 'write' | 'admin';
+export declare const KEY_SCOPE_LEVELS: readonly KeyScopeLevel[];
+/** A title as the authorization plugin stores it: plain text, or an i18n key in a namespace. */
+export type LocalizedText = string | {
+    readonly key: string;
+    readonly ns: string;
+};
+/**
+ * One permission a group level covers, in the vocabulary plugins already declare: a page (`access`), an action of a
+ * settings item, or a business action. The application maps each to an authorization resource and action.
+ */
+export type AccessRef = {
+    readonly kind: 'page';
+    readonly id: string;
+} | {
+    readonly kind: 'settings';
+    readonly id: string;
+    readonly action: string;
+} | {
+    readonly kind: 'business';
+    readonly id: string;
+    readonly action: string;
+};
+/** The section a group is listed under, as GitHub lists repository, organization and account permissions. */
+export type KeyScopeCategory = 'business' | 'administration' | 'account';
+export interface KeyScopeGroupDeclaration {
+    /** `<plugin>.<area>`, such as `releases.apps`. */
+    readonly id: string;
+    readonly category: KeyScopeCategory;
+    readonly title: LocalizedText;
+    readonly description?: LocalizedText;
+    /** What each level adds; a level left out is not offered. */
+    readonly levels: Readonly<Partial<Record<KeyScopeLevel, readonly AccessRef[]>>>;
+    /**
+     * Whether the group may be limited to some records of a business ("only selected Apps"). Only the plugin's own
+     * guards can enforce this, through `KeyScope.objects(business)`; declare it only where they do.
+     */
+    readonly objects?: {
+        /** The business whose records are picked, such as `rel.apps`. At most one group per business. */
+        readonly business: string;
+        readonly title: LocalizedText;
+        /** Actions kept only while every record is in scope, such as creating one. */
+        readonly allowsUnscoped?: readonly AccessRef[];
+    };
+}
+export interface KeyScopePresetDeclaration {
+    readonly id: string;
+    readonly title: LocalizedText;
+    readonly description?: LocalizedText;
+    readonly groups: Readonly<Record<string, {
+        readonly level: KeyScopeLevel;
+        readonly objects?: 'all' | 'pick';
+    }>>;
+    /** The expiry the preset suggests, in days; null for none. */
+    readonly expiresInDays?: number | null;
+}
+/** One group of a key's scope: the level, and the record ids it is limited to (omitted or `all` for every record). */
+export interface KeyScopeGroupGrant {
+    readonly level: KeyScopeLevel;
+    readonly objects?: 'all' | readonly string[];
+}
+/** What a key's scope holds, group by group; a group left out grants nothing. */
+export interface KeyScopeInput {
+    readonly groups: Readonly<Record<string, KeyScopeGroupGrant>>;
+}
+/** The storage format's version, kept under `$v`. */
+export declare const KEY_SCOPE_FORMAT_VERSION = "1";
+/** The records a group grant is limited to; undefined when it reaches every record. */
+export declare function pickedObjects(grant: KeyScopeGroupGrant): readonly string[] | undefined;
+/** The levels up to and including `level`. */
+export declare function levelsUpTo(level: KeyScopeLevel): KeyScopeLevel[];
+/**
+ * A scope as Better Auth's `permissions` column holds it: each group's levels expanded (`"releases.apps":
+ * ["read","write"]`), picked records under `"<group>@"`, and the format version under `$v`. Better Auth treats
+ * `permissions` as server-only on create and update, so a key's holder cannot widen it through `/api-key/update`.
+ */
+export declare function encodeKeyScope(scope: KeyScopeInput): Record<string, string[]>;
+/** The scope a `permissions` value holds; null for a key without one. A value in an unknown format grants nothing. */
+export declare function decodeKeyScope(permissions: unknown): KeyScopeInput | null;
+/** A group as an editor shows it, with what the asking user holds at each level today. */
+export interface KeyScopeGroupView {
+    readonly id: string;
+    readonly category: KeyScopeCategory;
+    readonly title: LocalizedText;
+    readonly description: LocalizedText | null;
+    /** The levels offered, lowest first. */
+    readonly levels: readonly KeyScopeLevel[];
+    /** What each level adds, for a hover list. */
+    readonly access: Readonly<Partial<Record<KeyScopeLevel, readonly AccessRef[]>>>;
+    /** Whether the user for whom the key is made holds everything up to each level; false shows it greyed out. */
+    readonly held: Readonly<Partial<Record<KeyScopeLevel, boolean>>>;
+    readonly objects: {
+        readonly business: string;
+        readonly title: LocalizedText;
+    } | null;
+}
+export interface KeyScopePresetView {
+    readonly id: string;
+    readonly title: LocalizedText;
+    readonly description: LocalizedText | null;
+    readonly groups: KeyScopePresetDeclaration['groups'];
+    readonly expiresInDays: number | null;
+}
+/** `GET /api/apiKeys/scopeOptions`: what the editor offers. Empty `groups` means scoped keys are not offered. */
+export interface KeyScopeOptions {
+    readonly groups: readonly KeyScopeGroupView[];
+    readonly presets: readonly KeyScopePresetView[];
+    /** The longest a scoped key may live, in days; null when "never expires" is allowed. */
+    readonly maxScopedKeyDays: number | null;
+    /** The expiry the editor proposes, in days. */
+    readonly defaultExpiresInDays: number;
+    /**
+     * Whether the asking person may create keys of their own (`ScopedApiKeys.setOwnKeyPolicy`); sent by
+     * `/api/apiKeys/scopeOptions`, absent elsewhere.
+     */
+    readonly mayCreate?: boolean;
+}
+/** A record a group may be limited to. */
+export interface KeyScopeObject {
+    readonly id: string;
+    readonly title: string;
+    readonly description?: string;
+}
+/** A key as a list shows it: never its secret or hash. */
+export interface ApiKeyView {
+    readonly id: string;
+    readonly name: string | null;
+    readonly description: string | null;
+    /** The first characters of the key, to recognize it. */
+    readonly start: string | null;
+    readonly enabled: boolean;
+    readonly createdAt: string;
+    readonly expiresAt: string | null;
+    /** When the key was last used, as Better Auth records it. */
+    readonly lastUsedAt: string | null;
+    /** Null for a key that is its owner in full. */
+    readonly scope: KeyScopeInput | null;
+}
+/** `POST` a key: a name, an optional description, an expiry in days (null for none) and a scope (null for full). */
+export interface CreateApiKeyRequest {
+    readonly name: string;
+    readonly description?: string | null;
+    readonly expiresInDays: number | null;
+    readonly scope: KeyScopeInput | null;
+}
+/** A key just created or rotated: its secret, shown once. */
+export interface CreatedApiKey {
+    readonly key: ApiKeyView;
+    readonly secret: string;
+}
+//# sourceMappingURL=scopes.d.ts.map

package/dist/shared/scopes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scopes.d.ts","sourceRoot":"","sources":["../../shared/scopes.ts"],"names":[],"mappings":"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"}

package/dist/shared/scopes.js

@@ -0,0 +1,83 @@
+/**
+ * Key scopes as data: what a plugin declares it offers (permission groups and presets), what a key's scope holds, and
+ * how a scope is stored in Better Auth's `permissions` column. Nothing here imports another plugin, so a plugin that
+ * contributes a group writes a literal of the same shape without depending on this package.
+ *
+ * A scope only ever narrows: a key's effective permission is its owner's current permission intersected with the
+ * scope. A key without a scope (`permissions = null`) is its owner, exactly as before scopes existed.
+ */
+export const KEY_SCOPE_LEVELS = [
+    'read',
+    'write',
+    'admin',
+];
+/** The storage format's version, kept under `$v`. */
+export const KEY_SCOPE_FORMAT_VERSION = '1';
+/** The records a group grant is limited to; undefined when it reaches every record. */
+export function pickedObjects(grant) {
+    return grant.objects === undefined || grant.objects === 'all'
+        ? undefined
+        : grant.objects;
+}
+/** The levels up to and including `level`. */
+export function levelsUpTo(level) {
+    return KEY_SCOPE_LEVELS.slice(0, KEY_SCOPE_LEVELS.indexOf(level) + 1);
+}
+/**
+ * A scope as Better Auth's `permissions` column holds it: each group's levels expanded (`"releases.apps":
+ * ["read","write"]`), picked records under `"<group>@"`, and the format version under `$v`. Better Auth treats
+ * `permissions` as server-only on create and update, so a key's holder cannot widen it through `/api-key/update`.
+ */
+export function encodeKeyScope(scope) {
+    const encoded = {
+        $v: [KEY_SCOPE_FORMAT_VERSION],
+    };
+    for (const [id, grant] of Object.entries(scope.groups)) {
+        encoded[id] = levelsUpTo(grant.level);
+        const picked = pickedObjects(grant);
+        if (picked)
+            encoded[`${id}@`] = [...picked];
+    }
+    return encoded;
+}
+/** The scope a `permissions` value holds; null for a key without one. A value in an unknown format grants nothing. */
+export function decodeKeyScope(permissions) {
+    const value = typeof permissions === 'string' ? safeParse(permissions) : permissions;
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value !== 'object' || Array.isArray(value))
+        return { groups: {} };
+    const record = value;
+    const version = record.$v;
+    if (!Array.isArray(version) || version[0] !== KEY_SCOPE_FORMAT_VERSION)
+        return { groups: {} };
+    const groups = {};
+    for (const [id, levels] of Object.entries(record)) {
+        if (id === '$v' || id.endsWith('@') || !Array.isArray(levels))
+            continue;
+        const level = [...KEY_SCOPE_LEVELS]
+            .reverse()
+            .find((candidate) => levels.includes(candidate));
+        if (!level)
+            continue;
+        const objects = record[`${id}@`];
+        groups[id] = {
+            level,
+            ...(Array.isArray(objects)
+                ? {
+                    objects: objects.filter((item) => typeof item === 'string'),
+                }
+                : {}),
+        };
+    }
+    return { groups };
+}
+function safeParse(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return {};
+    }
+}
+//# sourceMappingURL=scopes.js.map