@teikyo/enkaku 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paul Le Cam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,72 @@
-# Temporary Holding Version
+# @teikyo/enkaku
 
-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.
+Enkaku RPC plugin for Sozai HTTP servers. It serves an Enkaku server over the Enkaku HTTP transport as the `enkaku:rpc` plugin, with access optionally gated by `access:grants` and delegated capabilities checked by `access:revocation`.
+
+## Install
+
+```sh
+pnpm add @teikyo/enkaku @sozai/http-server hono
+```
+
+## Usage
+
+Plugin name: `enkaku:rpc` (exported as `ENKAKU_RPC`).
+
+```ts
+import { createServer } from '@sozai/http-server'
+import { accessGrantsPlugin, accessRevocationPlugin } from '@teikyo/access'
+import { ENKAKU_RPC, enkakuPlugin } from '@teikyo/enkaku'
+import { hozonDBPlugin } from '@teikyo/hozon'
+
+const server = await createServer({
+  plugins: [
+    hozonDBPlugin({ db: 'app.db' }),
+    accessGrantsPlugin(),
+    accessRevocationPlugin(),
+    enkakuPlugin({
+      path: '/rpc',
+      identity: serverIdentity,
+      protocol,
+      handlers,
+      access: { grants: true, revocation: true },
+    }),
+  ],
+})
+await server.listen()
+```
+
+The plugin exports `{ server, transport }` to plugins depending on `ENKAKU_RPC`.
+
+## Options
+
+Every `serve()` parameter of `@enkaku/server` is accepted except `transport` and `signal`, plus:
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `path` | `string` | Path the transport is served on, for every HTTP method. Body size and response deadline limits are disabled for it, since the transport enforces its own. |
+| `transport` | `ServerTransportOptions` | Options for the `@enkaku/http-serve` transport, such as `allowedOrigin`. |
+| `access.grants` | `true \| Array<string>` | Admit the gated patterns through `access:grants`: `true` gates every procedure (`*`), a non-empty array the listed patterns. Requires an `identity`. |
+| `access.revocation` | `true` | Run the `access:revocation` hook on delegated capabilities, before the caller's own `verifyToken`. Requires an `identity`. |
+
+`dependsOn` follows the options: `access:grants` and `access:revocation` are only required when used.
+
+## Access rules
+
+With `access.grants`, the caller's `accessRules` are kept and the gated patterns are added with the grants predicate. A caller rule that overlaps a gated pattern is rejected when `enkakuPlugin()` is called, with `Access rule "<caller>" overlaps grant-gated pattern "<gated>"`: Enkaku admits a procedure on the first rule that allows it, so an overlapping rule could bypass the grant check. With `grants: true`, every caller rule overlaps `*`, so none may be given. Before the overlap check, every caller rule key and gated pattern is validated with `@kokuin/capability`'s `assertValidPattern` (exact names or a trailing `/*` wildcard); an invalid one throws `Invalid access rule pattern "<caller>"` or `Invalid grant-gated pattern "<gated>"`, so a typo such as `admin*` cannot slip past the check.
+
+The revocation hook only runs when Enkaku checks a capability, that is when a caller is admitted as a delegate of a granted subject; a granted issuer calling directly presents no capability.
+
+## CORS and shutdown
+
+The transport is the only layer setting CORS headers, from `transport.allowedOrigin`. Its origin check is Enkaku's own behaviour, not the plugin's:
+
+- Without `allowedOrigin`, any request carrying an `Origin` header is rejected with 403, which means every browser client.
+- With `allowedOrigin` set (without `*`), any request without an `Origin` header is rejected with 403, which includes most non-browser clients.
+
+On shutdown the plugin starts disposing the Enkaku server and disposes the transport. Disposing the transport shuts down its HTTP bridge, which comes from `@enkaku/http-serve` >= 0.21.4:
+
+- Requests still awaiting a reply are answered immediately with `503 { "error": "Server shutting down" }`, with the CORS headers the transport would have sent. Handlers are aborted during disposal, so their results are not delivered.
+- Open event stream responses end, after the writes already queued for them have been processed.
+- Requests arriving afterwards are answered with the same 503.
+
+This lets the HTTP server drain without waiting for `graceMs`. The server's disposal is awaited in the close phase, bounded by `limits.cleanupTimeoutMs` (default 30 000 ms).

package/lib/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Enkaku RPC plugin for Sozai HTTP servers, with grant-gated access and capability revocation.
+ *
+ * @module enkaku
+ */
+export { mountTransport } from './mount.js';
+export { ENKAKU_RPC, type EnkakuAccessParams, type EnkakuPluginParams, type EnkakuRPC, enkakuPlugin, } from './plugin.js';
+export { type BuildAccessRulesParams, buildAccessRules } from './rules.js';

package/lib/index.js

@@ -0,0 +1,7 @@
+/**
+ * Enkaku RPC plugin for Sozai HTTP servers, with grant-gated access and capability revocation.
+ *
+ * @module enkaku
+ */ export { mountTransport } from './mount.js';
+export { ENKAKU_RPC, enkakuPlugin } from './plugin.js';
+export { buildAccessRules } from './rules.js';

package/lib/mount.d.ts

@@ -0,0 +1,13 @@
+import { ServerTransport, type ServerTransportOptions } from '@enkaku/http-serve';
+import type { ProtocolDefinition } from '@enkaku/protocol';
+import type { AnyPluginName, PluginContext } from '@sozai/http-server';
+/**
+ * Create an Enkaku HTTP transport and serve it on every method at `path`. The body size limit and
+ * response deadline are disabled for the path: the transport enforces its own, and event streams
+ * stay open for as long as their session.
+ *
+ * The transport is the only layer setting CORS headers, from `options.allowedOrigin`. Disposing
+ * the transport shuts its HTTP bridge down: requests in flight and arriving later are answered
+ * with a 503 and event streams end.
+ */
+export declare function mountTransport<Protocol extends ProtocolDefinition>(ctx: PluginContext<ReadonlyArray<AnyPluginName>>, path: string, options?: ServerTransportOptions): ServerTransport<Protocol>;

package/lib/mount.js

@@ -0,0 +1,18 @@
+import { ServerTransport } from '@enkaku/http-serve';
+/**
+ * Create an Enkaku HTTP transport and serve it on every method at `path`. The body size limit and
+ * response deadline are disabled for the path: the transport enforces its own, and event streams
+ * stay open for as long as their session.
+ *
+ * The transport is the only layer setting CORS headers, from `options.allowedOrigin`. Disposing
+ * the transport shuts its HTTP bridge down: requests in flight and arriving later are answered
+ * with a 503 and event streams end.
+ */ export function mountTransport(ctx, path, options) {
+    const transport = new ServerTransport(options);
+    ctx.limits(path, {
+        bodyBytes: false,
+        timeoutMs: false
+    });
+    ctx.route('all', path, (c)=>transport.fetch(c.req.raw));
+    return transport;
+}

package/lib/plugin.d.ts

@@ -0,0 +1,30 @@
+import type { ServerTransport, ServerTransportOptions } from '@enkaku/http-serve';
+import type { ProtocolDefinition } from '@enkaku/protocol';
+import { type ServeParams, type Server } from '@enkaku/server';
+import { type AnyHTTPPlugin, type PluginName } from '@sozai/http-server';
+export type EnkakuRPC = {
+    server: Server<ProtocolDefinition>;
+    transport: ServerTransport<ProtocolDefinition>;
+};
+export declare const ENKAKU_RPC: PluginName<'enkaku:rpc', EnkakuRPC>;
+/** `Omit` applied to each member of a union, keeping the identity and `requireAuth` variants apart. */
+type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+export type EnkakuAccessParams = {
+    /** Admit procedures through `access:grants`: `true` gates every procedure, an array the listed patterns. */
+    grants?: true | Array<string>;
+    /** Reject revoked delegated capabilities through `access:revocation`. */
+    revocation?: true;
+};
+export type EnkakuPluginParams<Protocol extends ProtocolDefinition> = DistributiveOmit<ServeParams<Protocol>, 'transport' | 'signal'> & {
+    /** Path the transport is served on, for every HTTP method. */
+    path: string;
+    transport?: ServerTransportOptions;
+    access?: EnkakuAccessParams;
+};
+/**
+ * Serve an Enkaku RPC server on `path`. With `access.grants`, the gated patterns admit callers
+ * through `access:grants`; with `access.revocation`, delegated capabilities are checked against
+ * `access:revocation` before the caller's own `verifyToken` hook.
+ */
+export declare function enkakuPlugin<Protocol extends ProtocolDefinition>(params: EnkakuPluginParams<Protocol>): AnyHTTPPlugin;
+export {};

package/lib/plugin.js

@@ -0,0 +1,101 @@
+import { DEFAULT_RESOURCE_LIMITS, serve } from '@enkaku/server';
+import { pluginName } from '@sozai/http-server';
+import { ACCESS_GRANTS, ACCESS_REVOCATION } from '@teikyo/access';
+import { mountTransport } from './mount.js';
+import { buildAccessRules } from './rules.js';
+export const ENKAKU_RPC = pluginName()('enkaku:rpc');
+const denyAll = ()=>false;
+function gatedPatterns(grants) {
+    return grants === true ? [
+        '*'
+    ] : grants;
+}
+function composeVerifyToken(first, second) {
+    if (first == null || second == null) {
+        return first ?? second;
+    }
+    return async (token, raw)=>{
+        await first(token, raw);
+        await second(token, raw);
+    };
+}
+/**
+ * Serve an Enkaku RPC server on `path`. With `access.grants`, the gated patterns admit callers
+ * through `access:grants`; with `access.revocation`, delegated capabilities are checked against
+ * `access:revocation` before the caller's own `verifyToken` hook.
+ */ export function enkakuPlugin(params) {
+    const { path, transport: transportOptions, access = {}, ...serveParams } = params;
+    // Without an identity Enkaku performs no access checks, so neither option could take effect.
+    if (serveParams.identity == null) {
+        if (access.grants != null) {
+            throw new Error('access.grants requires an identity');
+        }
+        if (access.revocation != null) {
+            throw new Error('access.revocation requires an identity');
+        }
+    }
+    if (Array.isArray(access.grants) && access.grants.length === 0) {
+        throw new Error('access.grants must not be empty');
+    }
+    if (access.grants != null) {
+        // Fail at the call site rather than during server setup.
+        buildAccessRules({
+            accessRules: serveParams.accessRules,
+            gated: gatedPatterns(access.grants),
+            allow: denyAll
+        });
+    }
+    const dependsOn = [];
+    if (access.grants != null) {
+        dependsOn.push(ACCESS_GRANTS);
+    }
+    if (access.revocation != null) {
+        dependsOn.push(ACCESS_REVOCATION);
+    }
+    return {
+        name: ENKAKU_RPC,
+        dependsOn,
+        setup (ctx) {
+            let accessRules = serveParams.accessRules;
+            if (access.grants != null) {
+                accessRules = buildAccessRules({
+                    accessRules,
+                    gated: gatedPatterns(access.grants),
+                    allow: ctx.use(ACCESS_GRANTS).allow()
+                });
+            }
+            const revocationHook = access.revocation == null ? undefined : ctx.use(ACCESS_REVOCATION).verifyToken;
+            const verifyToken = composeVerifyToken(revocationHook, serveParams.verifyToken);
+            const transport = mountTransport(ctx, path, transportOptions);
+            const common = {
+                logger: serveParams.logger ?? ctx.logger,
+                verifyToken,
+                transport
+            };
+            const server = serveParams.identity == null ? serve({
+                ...serveParams,
+                ...common
+            }) : serve({
+                ...serveParams,
+                ...common,
+                accessRules
+            });
+            let disposing;
+            ctx.onShutdown(async ()=>{
+                disposing = server.dispose();
+                // Observed here so a rejection before the close hook is not unhandled; onClose reports it.
+                void disposing.catch(()=>{});
+                await transport.dispose();
+            });
+            ctx.onClose(async ()=>{
+                await (disposing ?? server.dispose());
+            }, {
+                timeoutMs: serveParams.limits?.cleanupTimeoutMs ?? DEFAULT_RESOURCE_LIMITS.cleanupTimeoutMs
+            });
+            return {
+                server: server,
+                transport: transport
+            };
+        }
+    };
+}

package/lib/rules.d.ts

@@ -0,0 +1,14 @@
+import type { AccessRules, AllowPredicate } from '@enkaku/server';
+export type BuildAccessRulesParams = {
+    /** Rules supplied by the caller, kept as they are. */
+    accessRules?: AccessRules;
+    /** Patterns admitted only through `allow`. */
+    gated: Array<string>;
+    allow: AllowPredicate;
+};
+/**
+ * Combine caller rules with grant-gated patterns. A caller rule overlapping a gated pattern is
+ * rejected: Enkaku admits a procedure on the first matching rule that allows it, so such a rule
+ * could bypass the grant check. Every pattern is validated with `assertValidPattern` first.
+ */
+export declare function buildAccessRules(params: BuildAccessRulesParams): AccessRules;

package/lib/rules.js

@@ -0,0 +1,41 @@
+import { assertValidPattern } from '@kokuin/capability';
+import { patternsOverlap } from '@teikyo/access';
+function assertPattern(kind, pattern) {
+    try {
+        assertValidPattern(pattern);
+    } catch (cause) {
+        throw new Error(`Invalid ${kind} pattern "${pattern}"`, {
+            cause
+        });
+    }
+}
+/**
+ * Combine caller rules with grant-gated patterns. A caller rule overlapping a gated pattern is
+ * rejected: Enkaku admits a procedure on the first matching rule that allows it, so such a rule
+ * could bypass the grant check. Every pattern is validated with `assertValidPattern` first.
+ */ export function buildAccessRules(params) {
+    const rules = {
+        ...params.accessRules
+    };
+    // Validate first: an invalid pattern (`admin*` for `admin/*`) matches nothing, so it would pass
+    // the overlap check while the caller rule it was meant to exclude admits without grants.
+    for (const caller of Object.keys(rules)){
+        assertPattern('access rule', caller);
+    }
+    for (const gated of params.gated){
+        assertPattern('grant-gated', gated);
+    }
+    for (const caller of Object.keys(rules)){
+        for (const gated of params.gated){
+            if (patternsOverlap(caller, gated)) {
+                throw new Error(`Access rule "${caller}" overlaps grant-gated pattern "${gated}"`);
+            }
+        }
+    }
+    for (const gated of params.gated){
+        rules[gated] = {
+            allow: params.allow
+        };
+    }
+    return rules;
+}

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@teikyo/enkaku",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Enkaku RPC plugin for Sozai HTTP servers",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TairuFramework/teikyo.git",
+    "directory": "packages/enkaku"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": "./lib/index.js"
+  },
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "files": [
+    "lib/*"
+  ],
+  "dependencies": {
+    "@enkaku/http-serve": "^0.21.4",
+    "@enkaku/protocol": "^0.21.4",
+    "@enkaku/server": "^0.21.4",
+    "@kokuin/capability": "^0.4.0",
+    "@sozai/http-server": "^0.1.0",
+    "@teikyo/access": "^0.1.1"
+  },
+  "devDependencies": {
+    "@enkaku/client": "^0.21.3",
+    "@enkaku/http-fetch": "^0.21.4",
+    "@kokuin/token": "^0.5.0",
+    "@teikyo/hozon": "^0.1.1",
+    "@types/node": "^26.6.4",
+    "del-cli": "^7.0.0",
+    "hono": "^4.13.13",
+    "vitest": "5.0.3"
+  },
+  "peerDependencies": {
+    "hono": "^4.13.13"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "pnpm run build:clean && pnpm run build:js && pnpm run build:types",
+    "build:clean": "del-cli lib",
+    "build:js": "del-cli \"lib/**/*.js\" && swc src -d ./lib --config-file ../../node_modules/@kigu/dev/swc.json --strip-leading-paths",
+    "build:types": "del-cli \"lib/**/*.d.ts\" \"lib/**/*.d.ts.map\" && tsc --emitDeclarationOnly --skipLibCheck",
+    "build:types:ci": "tsc --emitDeclarationOnly --skipLibCheck --declarationMap false",
+    "test": "pnpm run test:types && pnpm run test:unit",
+    "test:types": "tsc --noEmit --skipLibCheck -p tsconfig.test.json",
+    "test:unit": "vitest run"
+  }
 }