@adminiumjs/adminium 0.1.0-rc.1

package/dist/plugins/rbac.js

@@ -0,0 +1,103 @@
+/**
+ * `rbac` plugin (08-server-api.md §5, M2-T05): decorates
+ *
+ * - `request.can(permission)` — lazy, per-request-cached allow/deny against
+ *   the resolved permission set (union of role grants; super-admin bypass;
+ *   deny-by-default),
+ * - `app.rbac.require(permission)` — route `preHandler` that throws
+ *   `ForbiddenError` with the missing permission in `details` and writes an
+ *   `rbac`-category `permission.denied` audit entry,
+ * - `app.rbac.audit(request, entry)` — actor/ip/ua/request-id-stamped audit
+ *   append for the mutating routes in this wave,
+ * - the API-key request-auth path: `Authorization: Bearer adm_sk_…` →
+ *   hashed lookup → `request.apiKeyPrincipal` acting with the key's role
+ *   (§2.16), with a throttled `last_used_at` touch.
+ *
+ * Session users arrive as `request.user` from `plugins/auth.ts`; this plugin
+ * only *reads* that decoration (structurally — see rbac/principal.ts).
+ */
+import fp from 'fastify-plugin';
+import { apiKeysRepo, auditRepo, } from '@adminium/meta';
+import { ForbiddenError, UnauthorizedError } from '../errors.js';
+import { API_KEY_TOUCH_INTERVAL_MS, hashApiKey, parseBearerApiKey, } from '../rbac/api-keys.js';
+import { parsePermission } from '../rbac/permissions.js';
+import { getPrincipal } from '../rbac/principal.js';
+import { permissionSetAllows, resolvePermissionSet, } from '../rbac/resolver.js';
+export const rbacPlugin = fp(async (app, opts) => {
+    const { meta } = opts;
+    const now = opts.now ?? Date.now;
+    const audit = auditRepo(meta);
+    const apiKeys = apiKeysRepo(meta);
+    app.decorateRequest('apiKeyPrincipal', null);
+    app.decorateRequest('rbacResolution', null);
+    async function resolve(request) {
+        // `!= null` (not `!== null`): routes registered in encapsulation
+        // contexts created BEFORE this plugin (e.g. bootstrap, inside
+        // buildServer) never get the decorator default, so the property reads
+        // `undefined` there — which must mean "not resolved yet", not a cache hit.
+        if (request.rbacResolution != null)
+            return request.rbacResolution;
+        const principal = getPrincipal(request);
+        if (principal === null) {
+            throw new UnauthorizedError();
+        }
+        const set = await resolvePermissionSet(meta, principal);
+        request.rbacResolution = set;
+        return set;
+    }
+    app.decorateRequest('can', async function can(permission) {
+        if (getPrincipal(this) === null)
+            return false;
+        return permissionSetAllows(await resolve(this), permission);
+    });
+    async function auditFromRequest(request, entry) {
+        const principal = getPrincipal(request);
+        await audit.append({
+            ...entry,
+            actorKind: principal?.kind ?? 'system',
+            actorId: principal?.id ?? null,
+            actorLabel: principal?.label ?? 'Adminium',
+            ip: request.ip ?? null,
+            userAgent: typeof request.headers['user-agent'] === 'string' ? request.headers['user-agent'] : null,
+            requestId: request.id,
+        }, now());
+    }
+    function require(permission) {
+        if (parsePermission(permission) === null) {
+            // Fail at registration time, not per-request: a guard on a permission
+            // outside the grammar is a programming error, not a client 403.
+            throw new Error(`rbac.require(): invalid permission ${JSON.stringify(permission)}`);
+        }
+        return async (request) => {
+            const set = await resolve(request); // throws 401 when unauthenticated
+            if (permissionSetAllows(set, permission))
+                return;
+            await auditFromRequest(request, {
+                category: 'rbac',
+                action: 'permission.denied',
+                changes: { after: { permission, method: request.method, url: request.url } },
+            });
+            throw new ForbiddenError('You do not have the required permission.', 'FORBIDDEN', {
+                permission,
+            });
+        };
+    }
+    app.decorate('rbac', { meta, require, resolve, audit: auditFromRequest, now });
+    // API-key request-auth path (§2.16): only engages for Bearer adm_sk_* —
+    // cookie sessions and other bearer schemes pass through untouched.
+    app.addHook('onRequest', async (request) => {
+        const key = parseBearerApiKey(request.headers.authorization);
+        if (key === null)
+            return;
+        const at = now();
+        const row = await apiKeys.findValidByTokenHash(hashApiKey(key), at);
+        if (row === null) {
+            throw new UnauthorizedError('UNAUTHENTICATED', 'Invalid, expired, or revoked API key.');
+        }
+        request.apiKeyPrincipal = { kind: 'api-key', id: row.id, label: row.name, roleId: row.roleId };
+        if (row.lastUsedAt === null || at - row.lastUsedAt >= API_KEY_TOUCH_INTERVAL_MS) {
+            await apiKeys.touchLastUsed(row.id, at);
+        }
+    });
+}, { name: 'adminium-rbac', fastify: '5.x' });
+//# sourceMappingURL=rbac.js.map

package/dist/plugins/rbac.js.map

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

package/dist/plugins/static.d.ts

@@ -0,0 +1,12 @@
+declare module 'fastify' {
+    interface FastifyInstance {
+        /** Absolute dashboard-build root being served, or null when disabled. */
+        spaRoot: string | null;
+    }
+}
+export interface StaticPluginOptions {
+    /** Candidate dashboard build directory; must contain `index.html`. */
+    root?: string | undefined;
+}
+export declare const staticPlugin: import("fastify").FastifyPluginCallback<StaticPluginOptions, import("fastify").RawServerDefault, import("fastify").FastifyTypeProviderDefault, import("fastify").FastifyBaseLogger>;
+//# sourceMappingURL=static.d.ts.map

package/dist/plugins/static.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"static.d.ts","sourceRoot":"","sources":["../../src/plugins/static.ts"],"names":[],"mappings":"AAaA,OAAO,QAAQ,SAAS,CAAC;IACvB,UAAU,eAAe;QACvB,yEAAyE;QACzE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;KACxB;CACF;AAED,MAAM,WAAW,mBAAmB;IAClC,sEAAsE;IACtE,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3B;AAED,eAAO,MAAM,YAAY,qLA2BxB,CAAC"}

package/dist/plugins/static.js

@@ -0,0 +1,36 @@
+/**
+ * `static` plugin (08-server-api.md §1.2): serves a dashboard build directory
+ * when one exists, with an SPA fallback to `index.html` for non-`/api/*`
+ * GET/HEAD requests (the fallback itself lives in the app's not-found handler,
+ * keyed off the `spaRoot` decoration). When the directory is absent — the
+ * dashboard ships M4 — the plugin cleanly no-ops and the server still boots.
+ */
+import { stat } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import fastifyStatic from '@fastify/static';
+import fp from 'fastify-plugin';
+export const staticPlugin = fp(async (app, opts) => {
+    let root = null;
+    if (opts.root !== undefined && opts.root !== '') {
+        const absolute = resolve(opts.root);
+        try {
+            const entry = await stat(join(absolute, 'index.html'));
+            if (entry.isFile())
+                root = absolute;
+        }
+        catch {
+            // Directory or index.html absent → serve nothing (no-op).
+        }
+    }
+    app.decorate('spaRoot', root);
+    if (root !== null) {
+        app.log.info({ root }, 'serving dashboard build');
+        await app.register(fastifyStatic, {
+            root,
+            // Wildcard route; missing files fall through to the not-found handler,
+            // which applies the SPA fallback for non-/api paths.
+            wildcard: true,
+        });
+    }
+}, { name: 'adminium-static', fastify: '5.x' });
+//# sourceMappingURL=static.js.map

package/dist/plugins/static.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"static.js","sourceRoot":"","sources":["../../src/plugins/static.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACxC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAE1C,OAAO,aAAa,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAchC,MAAM,CAAC,MAAM,YAAY,GAAG,EAAE,CAC5B,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;IAClB,IAAI,IAAI,GAAkB,IAAI,CAAC;IAE/B,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,IAAI,KAAK,EAAE,EAAE,CAAC;QAChD,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACpC,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAC;YACvD,IAAI,KAAK,CAAC,MAAM,EAAE;gBAAE,IAAI,GAAG,QAAQ,CAAC;QACtC,CAAC;QAAC,MAAM,CAAC;YACP,0DAA0D;QAC5D,CAAC;IACH,CAAC;IAED,GAAG,CAAC,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IAE9B,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAClB,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,EAAE,yBAAyB,CAAC,CAAC;QAClD,MAAM,GAAG,CAAC,QAAQ,CAAC,aAAa,EAAE;YAChC,IAAI;YACJ,uEAAuE;YACvE,qDAAqD;YACrD,QAAQ,EAAE,IAAI;SACf,CAAC,CAAC;IACL,CAAC;AACH,CAAC,EACD,EAAE,IAAI,EAAE,iBAAiB,EAAE,OAAO,EAAE,KAAK,EAAE,CAC5C,CAAC"}

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

@@ -0,0 +1,30 @@
+/**
+ * API-key secret handling (08-server-api.md §2.16): `adm_sk_` + 40 base62
+ * chars, shown exactly once at create time; only the SHA-256 hex hash and a
+ * short display/lookup prefix are stored (07-meta-store.md §3.7).
+ */
+export declare const API_KEY_PREFIX = "adm_sk_";
+/** Secret length after the prefix. */
+export declare const API_KEY_SECRET_LENGTH = 40;
+/** Stored display fragment: `adm_sk_` + first 8 secret chars (fits str(16)). */
+export declare const API_KEY_DISPLAY_PREFIX_LENGTH: number;
+/** `last_used_at` write throttle (07 §3.7 "throttled"). */
+export declare const API_KEY_TOUCH_INTERVAL_MS = 60000;
+/** SHA-256 hex of the full key string — the stored `token_hash`. */
+export declare function hashApiKey(key: string): string;
+export interface GeneratedApiKey {
+    /** The full secret — returned to the caller once, never stored. */
+    key: string;
+    /** Display/lookup fragment persisted in the `prefix` column. */
+    prefix: string;
+    /** SHA-256 hex persisted in the `token_hash` column. */
+    tokenHash: string;
+}
+export declare function generateApiKey(): GeneratedApiKey;
+/**
+ * Extract an Adminium API key from an `Authorization` header. Returns `null`
+ * unless the scheme is Bearer *and* the token carries the `adm_sk_` prefix —
+ * other bearer tokens fall through to the session/auth plugin untouched.
+ */
+export declare function parseBearerApiKey(authorization: string | undefined): string | null;
+//# sourceMappingURL=api-keys.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"api-keys.d.ts","sourceRoot":"","sources":["../../src/rbac/api-keys.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,eAAO,MAAM,cAAc,YAAY,CAAC;AAExC,sCAAsC;AACtC,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAExC,gFAAgF;AAChF,eAAO,MAAM,6BAA6B,QAA4B,CAAC;AAEvE,2DAA2D;AAC3D,eAAO,MAAM,yBAAyB,QAAS,CAAC;AAIhD,oEAAoE;AACpE,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED,MAAM,WAAW,eAAe;IAC9B,mEAAmE;IACnE,GAAG,EAAE,MAAM,CAAC;IACZ,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,cAAc,IAAI,eAAe,CAOhD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAMlF"}

package/dist/rbac/api-keys.js

@@ -0,0 +1,41 @@
+/**
+ * API-key secret handling (08-server-api.md §2.16): `adm_sk_` + 40 base62
+ * chars, shown exactly once at create time; only the SHA-256 hex hash and a
+ * short display/lookup prefix are stored (07-meta-store.md §3.7).
+ */
+import { createHash, randomInt } from 'node:crypto';
+export const API_KEY_PREFIX = 'adm_sk_';
+/** Secret length after the prefix. */
+export const API_KEY_SECRET_LENGTH = 40;
+/** Stored display fragment: `adm_sk_` + first 8 secret chars (fits str(16)). */
+export const API_KEY_DISPLAY_PREFIX_LENGTH = API_KEY_PREFIX.length + 8;
+/** `last_used_at` write throttle (07 §3.7 "throttled"). */
+export const API_KEY_TOUCH_INTERVAL_MS = 60_000;
+const BASE62 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+/** SHA-256 hex of the full key string — the stored `token_hash`. */
+export function hashApiKey(key) {
+    return createHash('sha256').update(key, 'utf8').digest('hex');
+}
+export function generateApiKey() {
+    let secret = '';
+    for (let i = 0; i < API_KEY_SECRET_LENGTH; i += 1) {
+        secret += BASE62[randomInt(BASE62.length)];
+    }
+    const key = `${API_KEY_PREFIX}${secret}`;
+    return { key, prefix: key.slice(0, API_KEY_DISPLAY_PREFIX_LENGTH), tokenHash: hashApiKey(key) };
+}
+/**
+ * Extract an Adminium API key from an `Authorization` header. Returns `null`
+ * unless the scheme is Bearer *and* the token carries the `adm_sk_` prefix —
+ * other bearer tokens fall through to the session/auth plugin untouched.
+ */
+export function parseBearerApiKey(authorization) {
+    if (authorization === undefined)
+        return null;
+    const match = /^Bearer\s+(\S+)$/i.exec(authorization.trim());
+    if (match === null)
+        return null;
+    const token = match[1];
+    return token.startsWith(API_KEY_PREFIX) ? token : null;
+}
+//# sourceMappingURL=api-keys.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"api-keys.js","sourceRoot":"","sources":["../../src/rbac/api-keys.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAEpD,MAAM,CAAC,MAAM,cAAc,GAAG,SAAS,CAAC;AAExC,sCAAsC;AACtC,MAAM,CAAC,MAAM,qBAAqB,GAAG,EAAE,CAAC;AAExC,gFAAgF;AAChF,MAAM,CAAC,MAAM,6BAA6B,GAAG,cAAc,CAAC,MAAM,GAAG,CAAC,CAAC;AAEvE,2DAA2D;AAC3D,MAAM,CAAC,MAAM,yBAAyB,GAAG,MAAM,CAAC;AAEhD,MAAM,MAAM,GAAG,gEAAgE,CAAC;AAEhF,oEAAoE;AACpE,MAAM,UAAU,UAAU,CAAC,GAAW;IACpC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAChE,CAAC;AAWD,MAAM,UAAU,cAAc;IAC5B,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,qBAAqB,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IAC7C,CAAC;IACD,MAAM,GAAG,GAAG,GAAG,cAAc,GAAG,MAAM,EAAE,CAAC;IACzC,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,6BAA6B,CAAC,EAAE,SAAS,EAAE,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;AAClG,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,aAAiC;IACjE,IAAI,aAAa,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IAC7C,MAAM,KAAK,GAAG,mBAAmB,CAAC,IAAI,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC,CAAC;IAC7D,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAChC,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAW,CAAC;IACjC,OAAO,KAAK,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;AACzD,CAAC"}

package/dist/rbac/index.d.ts

@@ -0,0 +1,6 @@
+/** RBAC internals barrel (permission grammar, resolver, principal, API keys). */
+export * from './permissions.js';
+export * from './principal.js';
+export * from './resolver.js';
+export * from './api-keys.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/rbac/index.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC"}

package/dist/rbac/index.js

@@ -0,0 +1,6 @@
+/** RBAC internals barrel (permission grammar, resolver, principal, API keys). */
+export * from './permissions.js';
+export * from './principal.js';
+export * from './resolver.js';
+export * from './api-keys.js';
+//# sourceMappingURL=index.js.map

package/dist/rbac/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/rbac/index.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC"}

package/dist/rbac/permissions.d.ts

@@ -0,0 +1,107 @@
+/**
+ * RBAC permission grammar (08-server-api.md §5.1) and its mapping onto the
+ * `adminium_role_permissions` matrix rows (07-meta-store.md §3.9).
+ *
+ * Grant strings:
+ *
+ * ```
+ * system:<area>:<verb>                      // closed set — meta SYSTEM_ACTION_KEYS,
+ *                                           // e.g. system:users:manage ⇔ `users.manage`
+ * table:<connectionId>:<table>:<action>     // action: read|create|update|delete|export|import
+ * page:<pageId>:<view|edit>
+ * ```
+ *
+ * Wildcards: `*` may stand in for any single segment of a stored `table:` or
+ * `page:` grant (`table:*:*:read`). Permissions *checked* at enforcement time
+ * are always concrete. `system:` grants are always concrete and validated
+ * against the v1 closed set. Deny-by-default: anything unparseable never
+ * matches anything.
+ *
+ * Reserved keys: meta's `RESERVED_SYSTEM_ACTION_KEYS` (automations.manage,
+ * webhooks.manage, manifests.manage, sql.run) are deferred features with no
+ * enforcement point in v1. The grammar here still accepts them — stored
+ * grants must keep round-tripping — but no permissions UI may offer them;
+ * grantable lists come from meta's `GRANTABLE_SYSTEM_ACTION_KEYS`.
+ */
+import { type PermissionActions, type ResourceKind, type RolePermission } from '@adminium/meta';
+/** Table matrix actions (07-meta-store.md §3.9 `actions` payload). */
+export declare const TABLE_ACTIONS: readonly ["read", "create", "update", "delete", "export", "import"];
+export type TableAction = (typeof TABLE_ACTIONS)[number];
+export declare const PAGE_ACTIONS: readonly ["view", "edit"];
+export type PageAction = (typeof PAGE_ACTIONS)[number];
+/** Canonical permission constants used by route guards in this wave. */
+export declare const PERMISSIONS: {
+    readonly usersManage: "system:users:manage";
+    readonly rolesManage: "system:roles:manage";
+    readonly settingsManage: "system:settings:manage";
+    readonly auditRead: "system:audit:read";
+    readonly apiKeysManage: "system:api-keys:manage";
+    readonly exportsManage: "system:exports:manage";
+    readonly importsManage: "system:imports:manage";
+    readonly reportsManage: "system:reports:manage";
+    readonly jobsRead: "system:jobs:read";
+    readonly jobsManage: "system:jobs:manage";
+};
+export type ParsedGrant = {
+    kind: 'system';
+    area: string;
+    verb: string;
+} | {
+    kind: 'table';
+    connectionId: string;
+    table: string;
+    action: TableAction | '*';
+} | {
+    kind: 'page';
+    pageId: string;
+    action: PageAction | '*';
+};
+/** A concrete (wildcard-free) permission, as passed to `can()`/`require()`. */
+export type ParsedPermission = {
+    kind: 'system';
+    area: string;
+    verb: string;
+} | {
+    kind: 'table';
+    connectionId: string;
+    table: string;
+    action: TableAction;
+} | {
+    kind: 'page';
+    pageId: string;
+    action: PageAction;
+};
+/**
+ * Parse a grant string (wildcards allowed on table/page segments).
+ * Returns `null` for anything outside the grammar — never throws.
+ */
+export declare function parseGrant(input: string): ParsedGrant | null;
+/** Parse a concrete permission for an enforcement check — no wildcards. */
+export declare function parsePermission(input: string): ParsedPermission | null;
+/** Does one stored grant satisfy one concrete required permission? */
+export declare function grantMatches(grant: string, required: string): boolean;
+/**
+ * Deny-by-default union check: exact set hit first, then the wildcard scan.
+ * `grants` must contain normalized grant strings (as produced by
+ * {@link grantsFromMatrixRows}).
+ */
+export declare function isGranted(grants: ReadonlySet<string>, required: string): boolean;
+/** Expand matrix rows into the flat, normalized grant-string union. */
+export declare function grantsFromMatrixRows(rows: readonly RolePermission[]): string[];
+export interface MatrixRowInput {
+    resourceKind: ResourceKind;
+    resourceRef: string;
+    actions: PermissionActions;
+}
+export interface MatrixConversion {
+    rows: MatrixRowInput[];
+    /** Grant strings outside the grammar (or unknown system keys). */
+    invalid: string[];
+}
+/**
+ * Group a `grants: string[]` payload (PUT /roles/:id/permissions) into matrix
+ * rows, merging grants that land on the same (kind, ref) cell. Invalid grants
+ * are collected instead of thrown so the route can 422 with the full list.
+ */
+export declare function matrixRowsFromGrants(grants: readonly string[]): MatrixConversion;
+//# sourceMappingURL=permissions.d.ts.map

package/dist/rbac/permissions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../../src/rbac/permissions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAGL,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,cAAc,EAEpB,MAAM,gBAAgB,CAAC;AAExB,sEAAsE;AACtE,eAAO,MAAM,aAAa,qEAAsE,CAAC;AACjG,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzD,eAAO,MAAM,YAAY,2BAA4B,CAAC;AACtD,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvD,wEAAwE;AACxE,eAAO,MAAM,WAAW;;;;;;;;;;;CAiBd,CAAC;AAEX,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,WAAW,GAAG,GAAG,CAAA;CAAE,GACjF;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,UAAU,GAAG,GAAG,CAAA;CAAE,CAAC;AAE/D,+EAA+E;AAC/E,MAAM,MAAM,gBAAgB,GACxB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,WAAW,CAAA;CAAE,GAC3E;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,UAAU,CAAA;CAAE,CAAC;AAWzD;;;GAGG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CA2B5D;AAED,2EAA2E;AAC3E,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAYtE;AAMD,sEAAsE;AACtE,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAsBrE;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAOhF;AAkBD,uEAAuE;AACvE,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,SAAS,cAAc,EAAE,GAAG,MAAM,EAAE,CAyB9E;AAED,MAAM,WAAW,cAAc;IAC7B,YAAY,EAAE,YAAY,CAAC;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,iBAAiB,CAAC;CAC5B;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,cAAc,EAAE,CAAC;IACvB,kEAAkE;IAClE,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAMD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,gBAAgB,CA0ChF"}

package/dist/rbac/permissions.js

@@ -0,0 +1,250 @@
+/**
+ * RBAC permission grammar (08-server-api.md §5.1) and its mapping onto the
+ * `adminium_role_permissions` matrix rows (07-meta-store.md §3.9).
+ *
+ * Grant strings:
+ *
+ * ```
+ * system:<area>:<verb>                      // closed set — meta SYSTEM_ACTION_KEYS,
+ *                                           // e.g. system:users:manage ⇔ `users.manage`
+ * table:<connectionId>:<table>:<action>     // action: read|create|update|delete|export|import
+ * page:<pageId>:<view|edit>
+ * ```
+ *
+ * Wildcards: `*` may stand in for any single segment of a stored `table:` or
+ * `page:` grant (`table:*:*:read`). Permissions *checked* at enforcement time
+ * are always concrete. `system:` grants are always concrete and validated
+ * against the v1 closed set. Deny-by-default: anything unparseable never
+ * matches anything.
+ *
+ * Reserved keys: meta's `RESERVED_SYSTEM_ACTION_KEYS` (automations.manage,
+ * webhooks.manage, manifests.manage, sql.run) are deferred features with no
+ * enforcement point in v1. The grammar here still accepts them — stored
+ * grants must keep round-tripping — but no permissions UI may offer them;
+ * grantable lists come from meta's `GRANTABLE_SYSTEM_ACTION_KEYS`.
+ */
+import { SYSTEM_ACTION_KEYS, } from '@adminium/meta';
+/** Table matrix actions (07-meta-store.md §3.9 `actions` payload). */
+export const TABLE_ACTIONS = ['read', 'create', 'update', 'delete', 'export', 'import'];
+export const PAGE_ACTIONS = ['view', 'edit'];
+/** Canonical permission constants used by route guards in this wave. */
+export const PERMISSIONS = {
+    usersManage: 'system:users:manage',
+    rolesManage: 'system:roles:manage',
+    settingsManage: 'system:settings:manage',
+    auditRead: 'system:audit:read',
+    apiKeysManage: 'system:api-keys:manage',
+    // M7 wave 2 (T5 data-io + T6 scheduled reports). The routes carry local
+    // constants (EXPORTS_MANAGE_PERMISSION / IMPORTS_MANAGE_PERMISSION /
+    // REPORTS_MANAGE_PERMISSION); these are the canonical spellings.
+    exportsManage: 'system:exports:manage',
+    importsManage: 'system:imports:manage',
+    reportsManage: 'system:reports:manage',
+    // Jobs (08 §2.17). The routes/realtime hub carry local constants
+    // (JOBS_READ_PERMISSION / JOBS_MANAGE_PERMISSION in realtime/hub.ts);
+    // these are the canonical spellings.
+    jobsRead: 'system:jobs:read',
+    jobsManage: 'system:jobs:manage',
+};
+const SYSTEM_KEY_SET = new Set(SYSTEM_ACTION_KEYS);
+const TABLE_ACTION_SET = new Set(TABLE_ACTIONS);
+const PAGE_ACTION_SET = new Set(PAGE_ACTIONS);
+/** Segments may not be empty and may not contain `:`, `/`, or whitespace. */
+function validSegment(segment) {
+    return segment.length > 0 && !/[:\s/]/.test(segment);
+}
+/**
+ * Parse a grant string (wildcards allowed on table/page segments).
+ * Returns `null` for anything outside the grammar — never throws.
+ */
+export function parseGrant(input) {
+    const segments = input.split(':');
+    const kind = segments[0];
+    if (kind === 'system' && segments.length === 3) {
+        const [, area, verb] = segments;
+        if (!validSegment(area) || !validSegment(verb))
+            return null;
+        if (area === '*' || verb === '*')
+            return null; // system grants are concrete
+        if (!SYSTEM_KEY_SET.has(`${area}.${verb}`))
+            return null; // v1 closed set
+        return { kind: 'system', area, verb };
+    }
+    if (kind === 'table' && segments.length === 4) {
+        const [, connectionId, table, action] = segments;
+        if (!validSegment(connectionId) || !validSegment(table))
+            return null;
+        if (action !== '*' && !TABLE_ACTION_SET.has(action))
+            return null;
+        return { kind: 'table', connectionId, table, action: action };
+    }
+    if (kind === 'page' && segments.length === 3) {
+        const [, pageId, action] = segments;
+        if (!validSegment(pageId))
+            return null;
+        if (action !== '*' && !PAGE_ACTION_SET.has(action))
+            return null;
+        return { kind: 'page', pageId, action: action };
+    }
+    return null;
+}
+/** Parse a concrete permission for an enforcement check — no wildcards. */
+export function parsePermission(input) {
+    const parsed = parseGrant(input);
+    if (parsed === null)
+        return null;
+    if (parsed.kind === 'table') {
+        if (parsed.connectionId === '*' || parsed.table === '*' || parsed.action === '*')
+            return null;
+        return parsed;
+    }
+    if (parsed.kind === 'page') {
+        if (parsed.pageId === '*' || parsed.action === '*')
+            return null;
+        return parsed;
+    }
+    return parsed;
+}
+function segmentMatches(grantSegment, requiredSegment) {
+    return grantSegment === '*' || grantSegment === requiredSegment;
+}
+/** Does one stored grant satisfy one concrete required permission? */
+export function grantMatches(grant, required) {
+    const g = parseGrant(grant);
+    const r = parsePermission(required);
+    if (g === null || r === null || g.kind !== r.kind)
+        return false;
+    switch (r.kind) {
+        case 'system': {
+            const gs = g;
+            return gs.area === r.area && gs.verb === r.verb;
+        }
+        case 'table': {
+            const gt = g;
+            return (segmentMatches(gt.connectionId, r.connectionId) &&
+                segmentMatches(gt.table, r.table) &&
+                segmentMatches(gt.action, r.action));
+        }
+        case 'page': {
+            const gp = g;
+            return segmentMatches(gp.pageId, r.pageId) && segmentMatches(gp.action, r.action);
+        }
+    }
+}
+/**
+ * Deny-by-default union check: exact set hit first, then the wildcard scan.
+ * `grants` must contain normalized grant strings (as produced by
+ * {@link grantsFromMatrixRows}).
+ */
+export function isGranted(grants, required) {
+    if (parsePermission(required) === null)
+        return false;
+    if (grants.has(required))
+        return true;
+    for (const grant of grants) {
+        if (grant.includes('*') && grantMatches(grant, required))
+            return true;
+    }
+    return false;
+}
+// --- matrix-row ⇄ grant-string mapping ---------------------------------------
+/** `table` resource_ref is `<connectionId>/<schema.table>` (07 §3.9). */
+function splitTableRef(resourceRef) {
+    const slash = resourceRef.indexOf('/');
+    if (slash <= 0 || slash === resourceRef.length - 1)
+        return null;
+    return { connectionId: resourceRef.slice(0, slash), table: resourceRef.slice(slash + 1) };
+}
+/** `system` resource_ref is the dotted action key, e.g. `users.manage`. */
+function splitSystemRef(resourceRef) {
+    const dot = resourceRef.indexOf('.');
+    if (dot <= 0 || dot === resourceRef.length - 1)
+        return null;
+    return { area: resourceRef.slice(0, dot), verb: resourceRef.slice(dot + 1) };
+}
+/** Expand matrix rows into the flat, normalized grant-string union. */
+export function grantsFromMatrixRows(rows) {
+    const grants = [];
+    for (const row of rows) {
+        if (row.resourceKind === 'system') {
+            const ref = splitSystemRef(row.resourceRef);
+            if (ref !== null && row.actions.allowed === true) {
+                grants.push(`system:${ref.area}:${ref.verb}`);
+            }
+            continue;
+        }
+        if (row.resourceKind === 'table') {
+            const ref = splitTableRef(row.resourceRef);
+            if (ref === null)
+                continue;
+            const actions = row.actions;
+            for (const action of TABLE_ACTIONS) {
+                if (actions[action] === true)
+                    grants.push(`table:${ref.connectionId}:${ref.table}:${action}`);
+            }
+            continue;
+        }
+        const actions = row.actions;
+        for (const action of PAGE_ACTIONS) {
+            if (actions[action] === true)
+                grants.push(`page:${row.resourceRef}:${action}`);
+        }
+    }
+    return grants;
+}
+function emptyTableActions() {
+    return { read: false, create: false, update: false, delete: false, export: false, import: false };
+}
+/**
+ * Group a `grants: string[]` payload (PUT /roles/:id/permissions) into matrix
+ * rows, merging grants that land on the same (kind, ref) cell. Invalid grants
+ * are collected instead of thrown so the route can 422 with the full list.
+ */
+export function matrixRowsFromGrants(grants) {
+    const invalid = [];
+    const tableRows = new Map();
+    const pageRows = new Map();
+    const systemRefs = new Set();
+    for (const grant of grants) {
+        const parsed = parseGrant(grant);
+        if (parsed === null) {
+            invalid.push(grant);
+            continue;
+        }
+        if (parsed.kind === 'system') {
+            systemRefs.add(`${parsed.area}.${parsed.verb}`);
+            continue;
+        }
+        if (parsed.kind === 'table') {
+            const ref = `${parsed.connectionId}/${parsed.table}`;
+            const actions = tableRows.get(ref) ?? emptyTableActions();
+            if (parsed.action === '*') {
+                for (const action of TABLE_ACTIONS)
+                    actions[action] = true;
+            }
+            else {
+                actions[parsed.action] = true;
+            }
+            tableRows.set(ref, actions);
+            continue;
+        }
+        const actions = pageRows.get(parsed.pageId) ?? { view: false, edit: false };
+        if (parsed.action === '*') {
+            actions.view = true;
+            actions.edit = true;
+        }
+        else {
+            actions[parsed.action] = true;
+        }
+        pageRows.set(parsed.pageId, actions);
+    }
+    const rows = [];
+    for (const ref of systemRefs)
+        rows.push({ resourceKind: 'system', resourceRef: ref, actions: { allowed: true } });
+    for (const [ref, actions] of tableRows)
+        rows.push({ resourceKind: 'table', resourceRef: ref, actions });
+    for (const [ref, actions] of pageRows)
+        rows.push({ resourceKind: 'page', resourceRef: ref, actions });
+    return { rows, invalid };
+}
+//# sourceMappingURL=permissions.js.map