@alneas/eaos-plugin-admin API

@alneas/eaos-plugin-admin API

Public entrypoints

Import	Contract
@alneas/eaos-plugin-admin/journal-workspace	Typed public export
@alneas/eaos-plugin-admin/user-help	Typed public export
@alneas/eaos-plugin-admin	Typed public export
@alneas/eaos-plugin-admin/manifest	Typed public export
@alneas/eaos-plugin-admin/client/web/journal	Typed public export
@alneas/eaos-plugin-admin/runtime	Typed public export
@alneas/eaos-plugin-admin/user-guide.json	Packaged JSON contract/data asset; resolve this exported path with the host loader
@alneas/eaos-plugin-admin/deployment.json	Packaged JSON contract/data asset; resolve this exported path with the host loader
@alneas/eaos-plugin-admin/eaos.clients.json	Packaged JSON contract/data asset; resolve this exported path with the host loader

[INTERFACE] AdminOptions

Host capabilities for resource authorization, tenant-scoped SQL and durable audit.

Imports: @alneas/eaos-plugin-admin.

Signature

interface AdminOptions {
    resources: AdminResource[];
    authorize(principal: PluginPrincipal, resource: AdminResource): Promise<boolean>;
    driver(principal: PluginPrincipal): RecordSqlDriver;
    audit(event: {
        principal: PluginPrincipal;
        resourceId: string;
        operation: 'list' | 'schema' | 'read';
        count?: number;
    }): Promise<void>;
}

Parameters

Name	Type	Required	Description
resources	AdminResource[]	Yes	Explicit host resource catalog; cloned when routes are constructed.
authorize	Promise<boolean>	Yes	Live plugin activation, admin role and resource-permission check; must resolve true for access.
driver	RecordSqlDriver	Yes	Return a tenant-aware SQL driver; errors propagate to the request.
audit	Promise<void>	Yes	Persist a durable metadata-only audit receipt before returning data; failures deny the response, and record payloads must not be logged.

Returns

Type declaration; no runtime value.

See also

createAdminRoutes for a complete host integration example.

Public members

resources

Explicit host resource catalog; cloned when routes are constructed.

authorize

Live plugin activation, admin role and resource-permission check; must resolve true for access.

Parameters:

• principal: Verified tenant principal for this operation.
• resource: Host-catalog resource identifier.

Returns: True only when current host policy allows access; false denies access.

Remarks

Must check current plugin activation, admin role AND resource permission.

Errors and rejections

Propagates host adapter or SDK failures; async methods reject their Promise.

Example:

import type { AdminOptions, AdminResource } from '@alneas/eaos-plugin-admin';
import type { PluginPrincipal } from '@alneas/eaos-server/plugin-data';
export function canInspect(options: AdminOptions, principal: PluginPrincipal, resource: AdminResource) {
 return options.authorize(principal, resource);
}

driver

Return a tenant-aware SQL driver; errors propagate to the request.

Parameters:

• principal: Verified tenant principal for this operation.

Returns: A tenant-aware SQL driver.

Errors and rejections

Propagates host adapter or SDK failures; async methods reject their Promise.

Example:

import type { AdminOptions } from '@alneas/eaos-plugin-admin';
import type { PluginPrincipal } from '@alneas/eaos-server/plugin-data';
export function tenantDriver(options: AdminOptions, principal: PluginPrincipal) {
 return options.driver(principal); // Keep tenant predicates in all SQL executed through this driver.
}

audit

Persist a durable metadata-only audit receipt before returning data; failures deny the response, and record payloads must not be logged.

Parameters:

• event: Message or error event delivered by the host worker.

Returns: Resolves without a value after a durable receipt is written.

Remarks

Durable audit receipt required before returning data; no record payloads are logged.

Errors and rejections

Propagates host adapter or SDK failures; async methods reject their Promise.

Example:

import type { AdminOptions } from '@alneas/eaos-plugin-admin';
import type { PluginPrincipal } from '@alneas/eaos-server/plugin-data';
export async function recordInspection(options: AdminOptions, principal: PluginPrincipal, resourceId: string, count: number) {
 await options.audit({ principal, resourceId, operation: 'read', count });
 // Return protected results only after this durable acknowledgement and a fresh authorization check.
}

audit.event.principal

Verified current tenant/user principal responsible for the admitted resource operation.

audit.event.resourceId

Explicit trusted admin resource catalog ID; never a request-selected SQL table name.

audit.event.operation

Reported metadata-list, schema-inspection or data-read phase; audit is durably acknowledged before data is returned.

audit.event.count

Optional returned or verified row/event count; omitted for catalog and schema inspection.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[INTERFACE] AdminResource

Explicit trusted read-only table projection and optional existing command journal.

Imports: @alneas/eaos-plugin-admin.

Signature

interface AdminResource {
    journal?: AtomicRepository;
    recordNamespace?: string;
    id: string;
    label: string;
    table: string;
    tenantColumn: string;
    keyColumn: string;
    columns: {
        name: string;
        label: string;
        type: 'string' | 'number' | 'boolean';
    }[];
}

Parameters

Name	Type	Required	Description
journal	AtomicRepository	No	Optional existing host-owned AtomicRepository; no discovery or journal creation is performed.
recordNamespace	string	No	Optional canonical record namespace restricting key prefixes; lowercase identifier, maximum 63 characters.
id	string	Yes	Unique trusted resource identifier, maximum 63 SQL-safe identifier characters.
label	string	Yes	Public catalog caption.
table	string	Yes	Trusted SQL table identifier; no user-supplied table names.
tenantColumn	string	Yes	SQL column constrained to the authenticated tenant on every query.
keyColumn	string	Yes	Stable SQL key used for ordering and optional namespace prefix checks.
columns	{ name: string; label: string; type: 'string' | 'number' | 'boolean'; }[]	Yes	Nonempty allowlist of at most 100 unique case-insensitive column names, public captions and scalar types.

Returns

Type declaration; no runtime value.

See also

createAdminRoutes for a complete host integration example.

Public members

journal

Optional existing host-owned AtomicRepository; no discovery or journal creation is performed.

Remarks

Explicit host-owned existing command journal; no table discovery.

recordNamespace

Optional canonical record namespace restricting key prefixes; lowercase identifier, maximum 63 characters.

id

Unique trusted resource identifier, maximum 63 SQL-safe identifier characters.

label

Public catalog caption.

table

Trusted SQL table identifier; no user-supplied table names.

tenantColumn

SQL column constrained to the authenticated tenant on every query.

keyColumn

Stable SQL key used for ordering and optional namespace prefix checks.

columns

Nonempty allowlist of at most 100 unique case-insensitive column names, public captions and scalar types.

Remarks

Only these columns can be selected or filtered. Do not expose credentials or internal control tables.

columns[].name

Allowlisted SQL column name; never expose credentials.

columns[].label

Public catalog caption.

columns[].type

Native text input type; defaults to text.

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[FUNCTION] createAdminRoutes

Creates a read-only admin router over an explicit resource catalog with repeated authorization and durable audit.

Imports: @alneas/eaos-plugin-admin.

Signature

declare function createAdminRoutes(options: AdminOptions, resolvePrincipal: (c: Context) => Promise<PluginPrincipal | null>): hono.Hono<_alneas_eaos_server_plugin_data.PluginHttpEnv, hono_types.BlankSchema, "/">;

Parameters

Name	Type	Required	Description
options	AdminOptions	Yes	Live host persistence and authorization configuration; see AdminOptions.
resolvePrincipal	(c: Context) => Promise<PluginPrincipal | null>	Yes	Resolves current authenticated principal per Hono request, or null to deny access.

Returns

hono.Hono<_alneas_eaos_server_plugin_data.PluginHttpEnv, hono_types.BlankSchema, "/">

A Hono router ready to mount under the plugin API prefix.

Remarks

The host owns authentication, current tenant membership and plugin activation. Service errors become HTTP failures through the plugin router; adapter failures may propagate. Mutations can commit before a response failure; reload current state before retrying.

Errors and rejections

Construction rejects invalid host/schema bindings or malformed/duplicate resource catalog identifiers.

Example

import { createAdminRoutes, type AdminOptions } from '@alneas/eaos-plugin-admin';
export function connectRoutes(options: AdminOptions, resolvePrincipal: Parameters<typeof createAdminRoutes>[1]) {
 return createAdminRoutes(options, resolvePrincipal);
}

[FUNCTION] createExtension

Builds a host extension restricted to a verified, concrete tenant catalog.

Imports: @alneas/eaos-plugin-admin/runtime.

Signature

declare function createExtension(input: {
    tenantIds: string[];
    bindings?: PublicPluginBindings;
}): {
    apiVersion: 1;
    id: string;
    tenantIds: string[];
    manifests: _alneas_eaos_core.PluginManifest[];
    lifecycle: _alneas_eaos_server_lifecycle_engine.LifecyclePlugin[];
    routeFactories: {
        [x: string]: (options?: any) => any;
    };
};

Parameters

Name	Type	Required	Description
input	{ tenantIds: string[]; bindings?: PublicPluginBindings; }	Yes	Nonempty distinct concrete tenantIds plus required live bindings; wildcard IDs are rejected.

Returns

{ apiVersion: 1; id: string; tenantIds: string[]; manifests: _alneas_eaos_core.PluginManifest[]; lifecycle: _alneas_eaos_server_lifecycle_engine.LifecyclePlugin[]; routeFactories: { [x: string]: (options?: any) => any; }; }

An API-version-1 extension containing tenant IDs, configured manifest, lifecycle and route factories.

Remarks

This validates adapter presence and tenant admission, not the truth of host authorization. No activation or migration is executed. Principals outside the configured catalog resolve to null.

Errors and rejections

Error for empty/duplicate/wildcard tenant IDs or missing host adapter functions.

Public members

input.tenantIds

Verified nonempty catalog of distinct concrete tenant IDs; wildcards are rejected.

input.bindings

Required live host options and identity resolver; omitted bindings throw.

Example

import { createExtension, type PublicPluginBindings } from '@alneas/eaos-plugin-admin/runtime';
export function configureExtension(tenantIds: string[], bindings: PublicPluginBindings) { return createExtension({ tenantIds, bindings }); }

[FUNCTION] createPlugin

Binds static plugin metadata to the host-configured route factory.

Imports: @alneas/eaos-plugin-admin.

Signature

declare function createPlugin(options: AdminOptions, resolvePrincipal: (c: Context) => Promise<PluginPrincipal | null>): PluginManifest;

Parameters

Name	Type	Required	Description
options	AdminOptions	Yes	Live host configuration; see AdminOptions.
resolvePrincipal	(c: Context) => Promise<PluginPrincipal | null>	Yes	Current authenticated Hono principal resolver; null denies admission.

Returns

PluginManifest

A cloned PluginManifest with a createRoutes closure; no routes are instantiated until called.

Remarks

Supplying a manifest does not activate a tenant or perform migrations. Host admission and live authorization remain mandatory.

Example

import { createPlugin, type AdminOptions } from '@alneas/eaos-plugin-admin';
export function configure(options: AdminOptions, resolvePrincipal: Parameters<typeof createPlugin>[1]) { return createPlugin(options, resolvePrincipal); }

[FUNCTION] default

Renders authorized command-journal catalogs, paged audit events and local continuity verification.

Imports: @alneas/eaos-plugin-admin/journal-workspace, @alneas/eaos-plugin-admin/client/web/journal.

Signature

declare function AdminJournalWorkspace(): React.JSX.Element | null;

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

React.JSX.Element \| null

The audit workspace, or null outside a ready RecordWorkspaceProvider.

Remarks

Requires React,

Example

import * as React from 'react';
import AdminJournalWorkspace, { WorkspaceProvider } from '@alneas/eaos-plugin-admin/journal-workspace';
export function AuditPage(props: Omit<React.ComponentProps<typeof WorkspaceProvider>, 'children'>) { return <WorkspaceProvider {...props}><AdminJournalWorkspace/></WorkspaceProvider>; }

[FUNCTION] default

Renders the plugin’s bundled repository-authored user guide.

Imports: @alneas/eaos-plugin-admin/user-help.

Signature

declare function UserHelp(): React.JSX.Element;

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

React.JSX.Element

A collapsible UserGuide element containing static Japanese help.

Remarks

Requires React and

Example

import * as React from 'react';
import UserHelp from '@alneas/eaos-plugin-admin/user-help';
export function Help() { return <UserHelp/>; }

[CONSTANT] lifecycle

Declares lifecycle compatibility and schema dependencies for host orchestration.

Imports: @alneas/eaos-plugin-admin.

Signature

declare const lifecycle: LifecyclePlugin;

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Declared constant value.

Remarks

The host lifecycle engine owns installation and tenant admission; importing this value performs no migrations.

Example

import { lifecycle } from '@alneas/eaos-plugin-admin'
console.log(lifecycle.id, lifecycle.version)

[CONSTANT] manifest

Declares static plugin metadata, navigation, public storage contracts and API prefix.

Static metadata shared by documentation inspection and the host-configured factory.

Imports: @alneas/eaos-plugin-admin/manifest.

Signature

declare const manifest: PluginManifest;

Parameters

Name	Type	Required	Description
—	—	—	No call parameters.

Returns

Declared constant value.

Remarks

Inspection metadata only; use the package createPlugin factory with live host bindings to obtain routes. This declaration does not activate a tenant.

Example

import { manifest } from '@alneas/eaos-plugin-admin/manifest'
console.log(manifest.id, manifest.version)

[INTERFACE] PublicPluginBindings

Live host service configuration and current authenticated principal resolver.

Imports: @alneas/eaos-plugin-admin/runtime.

Signature

interface PublicPluginBindings {
    options: AdminOptions;
    resolvePrincipal(context: Context): Promise<PluginPrincipal | null>;
}

Parameters

Name	Type	Required	Description
options	AdminOptions	Yes	Live plugin service/storage/authorization configuration.
resolvePrincipal	Promise<PluginPrincipal | null>	Yes	Resolve current verified Hono request identity, or null to deny access; rejection propagates.

Returns

Type declaration; no runtime value.

See also

createAdminRoutes for a complete host integration example.

Public members

options

Live plugin service/storage/authorization configuration.

resolvePrincipal

Resolve current verified Hono request identity, or null to deny access; rejection propagates.

Parameters:

• context: Current Hono request context.

Returns: A verified current principal, or null to deny admission.

Errors and rejections

Propagates host adapter or SDK failures; async methods reject their Promise.

Example:

import type { PublicPluginBindings } from '@alneas/eaos-plugin-admin/runtime';
export function resolveRequest(bindings: PublicPluginBindings, context: Parameters<PublicPluginBindings['resolvePrincipal']>[0]) {
 return bindings.resolvePrincipal(context); // Null denies unauthenticated or unavailable identity.
}

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.

[FUNCTION] WorkspaceProvider

Compatibility re-export; its implementation and documentation are owned by the owning API reference.

Imports: @alneas/eaos-plugin-admin/journal-workspace, @alneas/eaos-plugin-admin/client/web/journal.

Signature

declare const RecordWorkspaceProvider: ({ tenantId, recordId, sessionKey, client, children }: WorkspaceProviderProps<unknown>) => react.DetailedReactHTMLElement<{
    role: "status";
}, HTMLElement> | react.FunctionComponentElement<react.ProviderProps<WorkspaceClient<unknown> | null>>;

Parameters

Name	Type	Required	Description
{ tenantId, recordId, sessionKey, client, children }	WorkspaceProviderProps<unknown>	Yes	See the upstream owning declaration.

Returns

react.DetailedReactHTMLElement<{ role: "status"; }, HTMLElement> \| react.FunctionComponentElement<react.ProviderProps<WorkspaceClient<unknown> \| null>>

Example

See the owning declaration and linked feature guide for usage; no standalone example is documented in source.