@kubun/plugin-service-api 0.14.0

package/LICENSE.md

@@ -0,0 +1,57 @@
+# The Prosperity Public License 3.0.0
+
+Contributor: Paul Le Cam
+
+Source Code: https://github.com/PaulLeCam/kubun
+
+## Purpose
+
+This license allows you to use and share this software for noncommercial purposes for free and to try this software for commercial purposes for thirty days.
+
+## Agreement
+
+In order to receive this license, you have to agree to its rules.  Those rules are both obligations under that agreement and conditions to your license.  Don't do anything with this software that triggers a rule you can't or won't follow.
+
+## Notices
+
+Make sure everyone who gets a copy of any part of this software from you, with or without changes, also gets the text of this license and the contributor and source code lines above.
+
+## Commercial Trial
+
+Limit your use of this software for commercial purposes to a thirty-day trial period.  If you use this software for work, your company gets one trial period for all personnel, not one trial per person.
+
+## Contributions Back
+
+Developing feedback, changes, or additions that you contribute back to the contributor on the terms of a standardized public software license such as [the Blue Oak Model License 1.0.0](https://blueoakcouncil.org/license/1.0.0), [the Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0.html), [the MIT license](https://spdx.org/licenses/MIT.html), or [the two-clause BSD license](https://spdx.org/licenses/BSD-2-Clause.html) doesn't count as use for a commercial purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, doesn't count as use for a commercial purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution doesn't count as use for a commercial purpose regardless of the source of funding or obligations resulting from the funding.
+
+## Defense
+
+Don't make any legal claim against anyone accusing this software, with or without changes, alone or with other technology, of infringing any patent.
+
+## Copyright
+
+The contributor licenses you to do everything with this software that would otherwise infringe their copyright in it.
+
+## Patent
+
+The contributor licenses you to do everything with this software that would otherwise infringe any patents they can license or become able to license.
+
+## Reliability
+
+The contributor can't revoke this license.
+
+## Excuse
+
+You're excused for unknowingly breaking [Notices](#notices) if you take all practical steps to comply within thirty days of learning you broke the rule.
+
+## No Liability
+
+***As far as the law allows, this software comes as is, without any warranty or condition, and the contributor won't be liable to anyone for any damages related to this software or this license, under any kind of legal claim.***

package/lib/index.d.ts

@@ -0,0 +1,102 @@
+import type { ProtocolDefinition, ServerTransportOf } from '@enkaku/protocol';
+import type { AccessRules } from '@enkaku/server';
+export type { AccessRules };
+/**
+ * Permissive protocol at the host's merge boundary. The host serves the union of
+ * the services it is configured with, so the concrete procedure map is not known
+ * statically — each service narrows its own protocol in its own `-api` package.
+ * `ProtocolDefinition` is `Record<string, AnyProcedureDefinition>`, which is the
+ * loosest shape Enkaku's `serve`/`Server` accept.
+ */
+export type ServiceProtocol = ProtocolDefinition;
+/** Server-side transport the host serves a merged service protocol over. */
+export type ServiceServerTransport = ServerTransportOf<ServiceProtocol>;
+/**
+ * Subject-authorization check made available to service handlers via their call
+ * context. A handler calls it to gate an action a caller asserts on another
+ * subject's behalf. This contract only PLUMBS it through; the host's enforcement
+ * semantics are defined by later work.
+ */
+export type ServiceAuthorizer = (params: {
+    /** Verified caller DID (the message issuer). */
+    iss: string;
+    /** Fully-qualified procedure name, e.g. `echo/ping`. */
+    procedure: string;
+    /** Caller-asserted subject the action is taken on behalf of, when present. */
+    subject?: string;
+}) => boolean | Promise<boolean>;
+/**
+ * Context a service handler receives: the Enkaku request-handler context
+ * (`message`/`param`/`signal`) augmented with the verified caller `iss` and a
+ * bound {@link authorize} check. Kept structural because the host serves a union
+ * of services and cannot know the concrete procedure's param/result statically; a
+ * concrete service narrows these against its own protocol.
+ *
+ * `iss` and the `procedure` name are host-supplied (from the verified signed
+ * message, not the handler), so a handler can gate a caller-asserted `subject`
+ * but cannot spoof who the caller is or which procedure is running.
+ */
+export type ServiceHandlerContext = {
+    message: unknown;
+    param: unknown;
+    signal: AbortSignal;
+    /** Verified caller DID (the signed message issuer), when the request is authenticated. */
+    iss?: string;
+    /**
+     * Ask the per-serve {@link ServiceAuthorizer} whether the verified caller may
+     * act for `subject`. `iss`/`procedure` are supplied by the host; only `subject`
+     * comes from the handler. With no `subject`, the caller acts only for itself.
+     */
+    authorize: (subject?: string) => Promise<boolean>;
+};
+/** A single namespaced procedure handler, e.g. the impl behind `echo/ping`. */
+export type ServiceHandler = (context: ServiceHandlerContext) => unknown | Promise<unknown>;
+/**
+ * Namespaced handler map for a service, e.g. `{ 'echo/ping': handler }`. This is
+ * the canonical service-handler-map type; Enkaku's `ProcedureHandlers<Protocol>`
+ * is the strongly-typed form a concrete service produces against its own protocol.
+ */
+export type Handlers = Record<string, ServiceHandler>;
+/**
+ * What a plugin passes to `registerProvider('service', impl)`: a named service's
+ * handlers plus its own access rules. `'service'` is the registry key (not
+ * repeated here); the engine wraps this with the envelope fields (`kind`,
+ * `transport`, `priority`).
+ */
+export type ServiceProviderImpl = {
+    name: string;
+    handlers: Handlers;
+    accessRules?: AccessRules;
+};
+/**
+ * Per-service configuration, keyed by service NAME. Discriminated by explicit
+ * key, never by shape-sniffing:
+ * - `boolean` — toggle a provider-registered service. `true` serves it with its
+ *   own access rules; `false` leaves it registered but not served.
+ * - `{ handlers }` — a CUSTOM service impl (optional `rules`). Its name must NOT
+ *   be provider-registered (that collision is a serve-time error).
+ * - `{ rules }` with no `handlers` — an access-rules OVERRIDE for a
+ *   provider-registered service.
+ * - `{}` (neither key) is equivalent to `true`.
+ */
+export type ServiceConfig = boolean | {
+    rules?: AccessRules;
+    handlers?: Handlers;
+};
+/** Parameters for a single host `serve()` call. */
+export type ServiceServerServeParams = {
+    /** Server-side transport this server reads and writes. */
+    transport: ServiceServerTransport;
+    /** Which services to serve, keyed by service name. See {@link ServiceConfig}. */
+    services: Record<string, ServiceConfig>;
+    /** Subject-auth check plumbed into each served handler's context. */
+    authorizer?: ServiceAuthorizer;
+    /**
+     * Disable auth for THIS serve — unauthenticated local mode; serves the
+     * configured services' procedures with no signature requirement.
+     * `accessRules`/`authorizer` are moot when set.
+     */
+    requireAuth?: false;
+    /** Aborts the server when signalled. */
+    signal?: AbortSignal;
+};

package/lib/index.js

@@ -0,0 +1,7 @@
+// Cross-plugin contract for the service framework: the shapes a service package
+// registers with the host (`registerProvider('service', impl)`) and the shapes a
+// host consumes to serve them over a transport. Types only — importing this
+// creates no runtime edge on the host plugin, so a service package stays
+// independently loadable. The host implements the serving; each concrete service
+// keeps its own typed protocol in its own `-api` package.
+/** Parameters for a single host `serve()` call. */ export { };

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@kubun/plugin-service-api",
+  "version": "0.14.0",
+  "keywords": [],
+  "license": "see LICENSE.md",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": "./lib/index.js"
+  },
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "files": [
+    "lib/*",
+    "LICENSE.md"
+  ],
+  "dependencies": {
+    "@enkaku/protocol": "^0.21.0",
+    "@enkaku/server": "^0.21.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "pnpm run build:clean && pnpm run build:js && pnpm run build:types",
+    "build:clean": "del lib",
+    "build:js": "swc src -d ./lib --config-file ../../node_modules/@kigu/dev/swc.json --strip-leading-paths",
+    "build:types": "tsc --emitDeclarationOnly --skipLibCheck",
+    "build:types:ci": "tsc --emitDeclarationOnly --declarationMap false",
+    "test": "pnpm run test:types",
+    "test:types": "tsc --noEmit --skipLibCheck"
+  }
+}