@ekka-ai/shelves 0.2.2

package/dist/contracts/shelves/registry.json

@@ -0,0 +1,129 @@
+{
+  "description": "EKKA's predefined shelves (E1 v3.3; ekka-ai/.github#674). RULES EVERY SHELF HERE FOLLOWS: (1) A read key set is an IDENTIFIER set, never a human name. Names collide, so a read by name can return the wrong person's record; a name may be a field and a list filter, never a unique key. (2) Money is an integer count of minor units (`money_minor`) plus a currency code (`currency_code`, ISO 4217) on the same shelf, never a float. (3) Frozen once published: a breaking change is a new interface_major beside the old one, never an edit in place. (4) A private shelf a company declares may never reuse an id listed here.",
+  "registry_version": 1,
+  "categories": [
+    {
+      "id": "hr",
+      "title": "People and pay"
+    }
+  ],
+  "shelves": [
+    {
+      "id": "hr.salary",
+      "category": "hr",
+      "interface_major": 1,
+      "title": "Pay for one person in one month",
+      "owner_rule": "hr",
+      "keys": [
+        {
+          "name": "id",
+          "type": "string",
+          "unique": true
+        },
+        {
+          "name": "month",
+          "type": "month",
+          "unique": true
+        },
+        {
+          "name": "name",
+          "type": "string",
+          "unique": false
+        }
+      ],
+      "verbs": [
+        "read",
+        "list"
+      ],
+      "fields": [
+        {
+          "name": "id",
+          "type": "string",
+          "required": true
+        },
+        {
+          "name": "name",
+          "type": "string",
+          "required": true
+        },
+        {
+          "name": "month",
+          "type": "month",
+          "required": true
+        },
+        {
+          "name": "currency",
+          "type": "currency_code",
+          "required": true
+        },
+        {
+          "name": "gross_minor",
+          "type": "money_minor",
+          "required": true
+        },
+        {
+          "name": "net_minor",
+          "type": "money_minor",
+          "required": true
+        }
+      ],
+      "page_cap": 100
+    },
+    {
+      "id": "hr.timesheet",
+      "category": "hr",
+      "interface_major": 1,
+      "title": "Minutes one person worked in one month",
+      "owner_rule": "hr",
+      "keys": [
+        {
+          "name": "id",
+          "type": "string",
+          "unique": true
+        },
+        {
+          "name": "name",
+          "type": "string",
+          "unique": false
+        },
+        {
+          "name": "month",
+          "type": "month",
+          "unique": false
+        }
+      ],
+      "verbs": [
+        "read",
+        "list"
+      ],
+      "fields": [
+        {
+          "name": "id",
+          "type": "string",
+          "required": true
+        },
+        {
+          "name": "name",
+          "type": "string",
+          "required": true
+        },
+        {
+          "name": "month",
+          "type": "month",
+          "required": true
+        },
+        {
+          "name": "minutes",
+          "type": "integer",
+          "required": true
+        },
+        {
+          "name": "approved",
+          "type": "boolean",
+          "required": true
+        }
+      ],
+      "page_cap": 100
+    }
+  ]
+}

package/dist/generate.d.ts

@@ -0,0 +1,6 @@
+import type { AnyShelf } from './shelf.js';
+export declare const GENERATED_HEADER: string;
+export declare const generate: (provider: {
+    id: string;
+    offerVersion: string;
+}, shelves: readonly AnyShelf[]) => string;

package/dist/generate.js

@@ -0,0 +1,44 @@
+/**
+ * THE GENERATOR: src/ekka/shelves.generated.ts, the one source for what the shelves add to the
+ * Business API (E1 spec v3.4, section 6 P4).
+ *
+ * It writes the capability ids (`shelf.<id>.read`), ONE principal per shelf (`ekka-shelf-<id>`,
+ * one key each) and the protocol routes with their prefix. The host's
+ * capability table imports these instead of anyone typing them in three places.
+ *
+ * ⛔ NO EXPORTER ROWS, NO SURFACES (spec v3.4, section 13). A Business API's API-catalog exporter
+ * must never make a shelf route callable through the API gate: that would let a plan reach the
+ * shelf around the shelf executor, its record check and its receipt. The host's exporter reads
+ * SHELF_ROUTE_PREFIX to REFUSE any catalog rule that admits it.
+ */
+import { buildOffer, capabilityOf, principalOf, ROUTES, SHELF_ROUTE_PREFIX } from './protocol.js';
+// ⛔ NO OFFER, NO DIGEST IN THIS FILE. The manifest is built at startup from the registered shelves
+// (spec P3), and a probe fixture can come from the service's configuration (a seeded synthetic
+// record), so a digest written here would disagree with the one served. One source: the startup.
+import { prepareShelves } from './plugin.js';
+export const GENERATED_HEADER = '// GENERATED by @ekka-ai/shelves (`npx @ekka-ai/shelves generate`). Do not edit: change the shelf classes or\n' +
+    '// src/ekka/policy.ts and generate again. `npx @ekka-ai/shelves generate --check` fails on drift (CI).\n';
+const lit = (v) => JSON.stringify(v, null, 2);
+export const generate = (provider, shelves) => {
+    prepareShelves(shelves); // refuses the same offers the plugin would refuse at startup
+    const ids = shelves.map((s) => s.descriptor.id).sort();
+    buildOffer(provider, shelves); // refuses a provider id or offer version EKKA could not show
+    const principalCaps = Object.fromEntries(ids.map((id) => [principalOf(id), [capabilityOf(id)]]));
+    return [
+        GENERATED_HEADER,
+        `export const SHELF_IDS = ${lit(ids)} as const;`,
+        '',
+        '/** One capability per shelf; read and list both require it. */',
+        `export const SHELF_CAPABILITY_IDS = ${lit(ids.map(capabilityOf))} as const;`,
+        '',
+        '/** One principal, so one key, per shelf. A key never reaches another shelf, or another shelf’s name. */',
+        `export const SHELF_PRINCIPAL_IDS = ${lit(ids.map(principalOf))} as const;`,
+        '',
+        `export const SHELF_PRINCIPAL_CAPABILITIES = ${lit(principalCaps)} as const;`,
+        '',
+        '/** The protocol routes. The exporter REFUSES any API-catalog rule that admits one of them. */',
+        `export const SHELF_ROUTES = ${lit(Object.values(ROUTES))} as const;`,
+        `export const SHELF_ROUTE_PREFIX = ${lit(SHELF_ROUTE_PREFIX)};`,
+        '',
+    ].join('\n');
+};

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/** The predefined shelves, read from the pinned contracts package, never copied. */
+export declare function predefinedShelves(): {
+    id: string;
+    interface_major: number;
+}[];
+export { ekkaShelves, prepareShelves, type EkkaShelvesOptions } from './plugin.js';
+export { Shelf, ShelfRefusal, notImplemented, predefined, privateShelf, verbProblems, type AnyShelf, type Fixtures, type ListResult, type Page, type RefusalCode, type Roles, type Row, type ShelfDescriptor, } from './shelf.js';
+export { PROTOCOL, ROUTES, SHELF_ROUTE_PREFIX, buildOffer, manifestFor, canonicalJson, capabilityOf, principalOf, type Manifest, type ManifestShelf, type Offer, } from './protocol.js';
+export { loadRegistry, registrySource, parseRegistry, type Registry, type PredefinedShelf, type Verb, type FieldType } from './registry.js';
+export { generate, GENERATED_HEADER } from './generate.js';
+export { add, className } from './scaffold.js';
+export { runCheck, formatCheck, type CheckTarget, type Transport, type Answer, type CheckLine } from './check.js';

package/dist/index.js

@@ -0,0 +1,22 @@
+/**
+ * @ekka-ai/shelves: the Business API side of E1 (ekka-ai/.github#674, E1-V3-SPEC section 6).
+ *
+ *   npx @ekka-ai/shelves add <id>     scaffold a typed shelf class (P1)
+ *   npx @ekka-ai/shelves generate     write src/ekka/shelves.generated.ts (P4)
+ *   npx @ekka-ai/shelves check        the real endpoint, the fixtures, what EKKA will see (P2)
+ *   app.register(ekkaShelves({...}))  mount the shelf protocol v1 (P3)
+ *
+ * The one source of truth is @ekka-ai/contracts (0.42.0): the shelf registry and protocol v1.
+ */
+import { loadRegistry } from './registry.js';
+/** The predefined shelves, read from the pinned contracts package, never copied. */
+export function predefinedShelves() {
+    return [...loadRegistry().shelves.values()].map(({ id, interfaceMajor }) => ({ id, interface_major: interfaceMajor }));
+}
+export { ekkaShelves, prepareShelves } from './plugin.js';
+export { Shelf, ShelfRefusal, notImplemented, predefined, privateShelf, verbProblems, } from './shelf.js';
+export { PROTOCOL, ROUTES, SHELF_ROUTE_PREFIX, buildOffer, manifestFor, canonicalJson, capabilityOf, principalOf, } from './protocol.js';
+export { loadRegistry, registrySource, parseRegistry } from './registry.js';
+export { generate, GENERATED_HEADER } from './generate.js';
+export { add, className } from './scaffold.js';
+export { runCheck, formatCheck } from './check.js';

package/dist/plugin.d.ts

@@ -0,0 +1,43 @@
+/**
+ * THE PLUGIN: one `register` mounts the shelf protocol on a Business API (E1 spec, section 6 P3).
+ *
+ *   await app.register(ekkaShelves({ provider, shelves, authenticate, authorize, capabilitiesOf, run }));
+ *
+ * ⛔ THE HOST OWNS AUTHORITY. This package never decides who a caller is. `authenticate` is the
+ * host's own bearer check (Trado: authenticatePrincipal + its org scope) and runs on every request
+ * but ping, BEFORE the body is looked at. `authorize(capability)` is the host's own guard (Trado:
+ * requireCapability) and runs for the one shelf named in the body. A thrown error from either is
+ * the host's answer; an authorize refusal is also mapped to the protocol's `forbidden`.
+ *
+ * ⛔ A SHELF THIS CREDENTIAL DOES NOT SERVE AND A SHELF THAT DOES NOT EXIST GET THE SAME ANSWER.
+ * A private shelf's name is a fact about the company; "no such shelf" would confirm or deny it.
+ */
+import type { FastifyPluginAsync, FastifyReply, FastifyRequest } from 'fastify';
+import { type ShelfValidators } from './protocol.js';
+import { type AnyShelf } from './shelf.js';
+type Hook = (request: FastifyRequest, reply: FastifyReply) => Promise<void> | void;
+export interface EkkaShelvesOptions {
+    readonly provider: {
+        readonly id: string;
+        readonly offerVersion: string;
+    };
+    readonly shelves: readonly AnyShelf[];
+    /** The host's bearer check. Throws its own 401 on a missing or unknown credential. */
+    readonly authenticate: Hook;
+    /** The host's own capability guard for one capability, e.g. Trado's requireCapability. */
+    readonly authorize: (capability: string) => Hook;
+    /** The capabilities of the principal `authenticate` found, read to filter the manifest. */
+    readonly capabilitiesOf: (request: FastifyRequest) => readonly string[];
+    /** The id of the principal `authenticate` found: the manifest names it. */
+    readonly principalOf: (request: FastifyRequest) => string;
+    /** The host's admission or limits around a method call. Defaults to calling it directly. */
+    readonly run?: <T>(request: FastifyRequest, work: () => Promise<T>) => Promise<T>;
+}
+interface Mounted {
+    readonly shelf: AnyShelf;
+    readonly v: ShelfValidators;
+}
+/** Validate the whole offer at startup: a shelf that cannot keep a promise must not be served. */
+export declare const prepareShelves: (shelves: readonly AnyShelf[]) => Map<string, Mounted>;
+export declare const ekkaShelves: (opts: EkkaShelvesOptions) => FastifyPluginAsync;
+export {};

package/dist/plugin.js

@@ -0,0 +1,125 @@
+import { buildOffer, capabilityOf, compileShelf, isInvokeRequest, manifestFor, PROTOCOL, recordProblem, REFUSAL_STATUS, refusalMessage, RESERVED_VERBS, ROUTES, undeclaredKeys, } from './protocol.js';
+import { ShelfRefusal, verbProblems } from './shelf.js';
+/** Validate the whole offer at startup: a shelf that cannot keep a promise must not be served. */
+export const prepareShelves = (shelves) => {
+    const out = new Map();
+    const problems = [];
+    for (const s of shelves) {
+        if (out.has(s.descriptor.id))
+            problems.push(`${s.descriptor.id} is registered twice`);
+        problems.push(...verbProblems(s));
+        out.set(s.descriptor.id, { shelf: s, v: compileShelf(s.descriptor.shape) });
+    }
+    if (problems.length)
+        throw new Error(`@ekka-ai/shelves refused to start:\n  - ${problems.join('\n  - ')}`);
+    return out;
+};
+export const ekkaShelves = (opts) => {
+    const mounted = prepareShelves(opts.shelves);
+    const offer = buildOffer(opts.provider, opts.shelves);
+    const run = opts.run ?? (async (_r, work) => work());
+    const plugin = async (app) => {
+        const envelope = (body) => ({
+            protocol: PROTOCOL,
+            request_id: body.request_id,
+            offer_version: opts.provider.offerVersion,
+            shelf: body.shelf,
+            verb: body.verb,
+        });
+        const refuse = (reply, code, message, body) => reply
+            .code(REFUSAL_STATUS[code])
+            .header('cache-control', 'no-store')
+            .send({ ...(body ? envelope(body) : { protocol: PROTOCOL }), refusal: { code, message: refusalMessage(message) } });
+        // The one public route: the protocol version, and no name of anything.
+        app.get(ROUTES.ping, async (_req, reply) => reply.header('cache-control', 'no-store').send({ protocol: PROTOCOL }));
+        app.get(ROUTES.manifest, { onRequest: opts.authenticate }, async (request, reply) => {
+            // PER-PRINCIPAL LISTING: shelf names can be a client list, so a key sees only its own.
+            const view = manifestFor(offer, opts.principalOf(request), opts.capabilitiesOf(request));
+            if (view.shelves.length === 0)
+                return refuse(reply, 'forbidden', 'this credential serves no shelf');
+            return reply.header('cache-control', 'no-store').send(view);
+        });
+        app.post(ROUTES.invoke, { onRequest: opts.authenticate, bodyLimit: 16 * 1024 }, async (request, reply) => {
+            const body = request.body;
+            if (!isInvokeRequest(body))
+                return refuse(reply, 'shape', 'not a shelf protocol v1 request');
+            const m = mounted.get(body.shelf);
+            const forbidden = () => refuse(reply, 'forbidden', 'this credential does not serve that shelf', body);
+            if (!m)
+                return forbidden();
+            try {
+                await opts.authorize(capabilityOf(body.shelf))(request, reply);
+            }
+            catch {
+                return forbidden();
+            }
+            const { shelf, v } = m;
+            const { shape, interfaceMajor, id } = shelf.descriptor;
+            if (RESERVED_VERBS.includes(body.verb)) {
+                return refuse(reply, 'not_implemented', `"${body.verb}" is reserved and not served in protocol v1`, body);
+            }
+            if (body.verb !== 'read' && body.verb !== 'list')
+                return refuse(reply, 'not_implemented', `no verb "${body.verb}"`, body);
+            const verb = body.verb;
+            if (!shape.verbs.includes(verb))
+                return refuse(reply, 'not_implemented', `${id} does not serve "${verb}"`, body);
+            // A private shelf has no registry major; protocol v1 serves it as interface 1.
+            const served = interfaceMajor ?? 1;
+            if (body.interface_major !== served) {
+                return refuse(reply, 'shape', `${id} is served at interface ${served}, not ${body.interface_major}`, body);
+            }
+            if (verb === 'read' && body.page !== undefined)
+                return refuse(reply, 'shape', 'a read takes no page', body);
+            // ⛔ AN UNDECLARED KEY IS REFUSED, NEVER IGNORED. Ignoring it would turn "read this person's
+            // salary" into "read someone's salary" the moment a key is misspelled.
+            const extra = undeclaredKeys(v, verb, body.by);
+            if (extra.length)
+                return refuse(reply, 'unknown_key', `${id} ${verb} does not take: ${extra.join(', ')}`, body);
+            try {
+                if (verb === 'read') {
+                    if (!v.readBy(body.by))
+                        return refuse(reply, 'shape', `${id} read takes exactly ${v.readKeys.join(', ')}, with their declared types`, body);
+                    const record = await run(request, () => shelf.read(body.by));
+                    if (record === null)
+                        return reply.header('cache-control', 'no-store').send({ ...envelope(body), result: { not_found: true } });
+                    if (!v.record(record)) {
+                        request.log.warn({ shelf: id, verb, problem: recordProblem(shape, record) }, 'shelf record refused on the way out');
+                        return refuse(reply, 'provider_error', 'the provider returned a record that is not this shelf’s shape', body);
+                    }
+                    return reply.header('cache-control', 'no-store').send({ ...envelope(body), result: { record } });
+                }
+                if (!v.listBy(body.by))
+                    return refuse(reply, 'shape', `${id} list filters on ${v.listKeys.join(', ')}, with their declared types`, body);
+                // protocol-v1 `page`: the provider returns at most min(limit, page_cap) records.
+                const limit = Math.min(body.page?.limit ?? shape.pageCap, shape.pageCap);
+                const page = { limit, cursor: body.page?.cursor ?? null };
+                const out = await run(request, () => shelf.list(body.by, page));
+                const bad = !out || !Array.isArray(out.records)
+                    ? 'no records array'
+                    : !(typeof out.nextCursor === 'string' || out.nextCursor === null)
+                        ? 'no next cursor (null when this is the last page)'
+                        : out.records.length > limit
+                            ? `${out.records.length} records for a page of ${limit}`
+                            : (() => {
+                                const i = out.records.findIndex((r) => !v.record(r));
+                                return i < 0 ? '' : `record ${i}: ${recordProblem(shape, out.records[i])}`;
+                            })();
+                if (bad || !out) {
+                    request.log.warn({ shelf: id, verb, problem: bad }, 'shelf page refused on the way out');
+                    return refuse(reply, 'provider_error', 'the provider returned a page that is not this shelf’s shape', body);
+                }
+                return reply
+                    .header('cache-control', 'no-store')
+                    .send({ ...envelope(body), result: { records: out.records, next_cursor: out.nextCursor } });
+            }
+            catch (err) {
+                if (err instanceof ShelfRefusal)
+                    return refuse(reply, err.code, err.message, body);
+                // The cause never travels: it can name a table, a host, or a value.
+                request.log.error({ shelf: id, verb, err }, 'shelf method failed');
+                return refuse(reply, 'provider_error', 'the provider could not answer', body);
+            }
+        });
+    };
+    return plugin;
+};

package/dist/protocol.d.ts

@@ -0,0 +1,131 @@
+import { Type } from 'typebox';
+import type { FieldType, ShelfShape, Verb } from './registry.js';
+import type { AnyShelf, RefusalCode, Row } from './shelf.js';
+export declare const PROTOCOL: 1;
+export declare const ROUTES: {
+    readonly ping: "/ekka/shelves/v1/ping";
+    readonly manifest: "/ekka/shelves/v1/manifest";
+    readonly invoke: "/ekka/shelves/v1/invoke";
+};
+export declare const SHELF_ROUTE_PREFIX = "/ekka/shelves/";
+/** Protocol-reserved verbs: named so a caller gets `not_implemented`, not "no such verb". */
+export declare const RESERVED_VERBS: readonly ["write", "update", "delete", "send"];
+/** protocol-v1 `invocation_assertion`: the Enclave's signed invocation. v1 providers MAY verify it. */
+export declare const InvocationAssertion: Type.TObject<{
+    alg: Type.TLiteral<"ed25519">;
+    key_id: Type.TString;
+    payload_b64: Type.TString;
+    sig_b64: Type.TString;
+}>;
+export declare const InvokeRequest: Type.TObject<{
+    protocol: Type.TLiteral<1>;
+    request_id: Type.TString;
+    shelf: Type.TString;
+    interface_major: Type.TInteger;
+    verb: Type.TString;
+    by: Type.TRecord<"^.*$", Type.TUnion<[Type.TString, Type.TInteger, Type.TBoolean]>>;
+    page: Type.TOptional<Type.TObject<{
+        limit: Type.TInteger;
+        cursor: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull]>>;
+    }>>;
+    auth: Type.TObject<{
+        alg: Type.TLiteral<"ed25519">;
+        key_id: Type.TString;
+        payload_b64: Type.TString;
+        sig_b64: Type.TString;
+    }>;
+}>;
+export type InvokeRequestBody = {
+    protocol: 1;
+    request_id: string;
+    shelf: string;
+    interface_major: number;
+    verb: string;
+    by: Record<string, string | number | boolean>;
+    page?: {
+        limit: number;
+        cursor?: string | null;
+    };
+    auth: {
+        alg: 'ed25519';
+        key_id: string;
+        payload_b64: string;
+        sig_b64: string;
+    };
+};
+export declare const isInvokeRequest: (v: unknown) => v is InvokeRequestBody;
+/** The HTTP status for each typed refusal; the body always carries the refusal itself. */
+export declare const REFUSAL_STATUS: Record<RefusalCode, number>;
+/** protocol-v1 `refusal.message` is at most 500 characters, and never a record value. */
+export declare const refusalMessage: (m: string) => string;
+/** The validators one shelf needs, compiled once at startup. */
+export interface ShelfValidators {
+    readonly readKeys: readonly string[];
+    readonly listKeys: readonly string[];
+    readonly readBy: (by: unknown) => boolean;
+    readonly listBy: (by: unknown) => boolean;
+    readonly record: (r: unknown) => boolean;
+}
+export declare const compileShelf: (shape: ShelfShape) => ShelfValidators;
+/** Which names in `by` this verb does not accept. Non-empty means `unknown_key`, never a guess. */
+export declare const undeclaredKeys: (v: ShelfValidators, verb: Verb, by: Record<string, unknown>) => string[];
+/** Why a returned record is not a record of this shelf, in words, never with its values. */
+export declare const recordProblem: (shape: ShelfShape, r: unknown) => string;
+/** Sorted keys, no whitespace (SECURITY.CANONICALIZE.V1 for integer-only JSON): same object, same bytes. */
+export declare const canonicalJson: (v: unknown) => string;
+export declare const sha256: (s: string) => string;
+/** protocol-v1 `manifest_shelf`: a predefined shelf carries interface_major, a private one its shape. */
+export interface ManifestShelf {
+    readonly id: string;
+    readonly origin: 'predefined' | 'private';
+    readonly interface_major?: number;
+    readonly shape?: {
+        readonly keys: readonly {
+            name: string;
+            type: FieldType;
+            unique: boolean;
+        }[];
+        readonly fields: readonly {
+            name: string;
+            type: FieldType;
+            required: boolean;
+        }[];
+        readonly page_cap: number;
+    };
+    readonly verbs: readonly Verb[];
+    readonly required_role: Readonly<Partial<Record<Verb, string>>>;
+    readonly probe_fixture: {
+        readonly synthetic: true;
+        readonly read?: Row;
+        readonly list?: Partial<Row>;
+    };
+}
+/** protocol-v1 `manifest`, as served to ONE principal. */
+export interface Manifest {
+    readonly protocol: 1;
+    readonly provider_id: string;
+    readonly offer_version: string;
+    /** Over the WHOLE offer, every shelf, whoever is looking: what an import pins. */
+    readonly digest: string;
+    readonly principal: string;
+    readonly shelves: readonly ManifestShelf[];
+}
+export declare const PROVIDER_ID: RegExp;
+export declare const manifestShelf: (s: AnyShelf) => ManifestShelf;
+export interface Offer {
+    readonly provider_id: string;
+    readonly offer_version: string;
+    readonly digest: string;
+    readonly shelves: readonly ManifestShelf[];
+}
+export declare const buildOffer: (provider: {
+    id: string;
+    offerVersion: string;
+}, shelves: readonly AnyShelf[]) => Offer;
+/** The manifest ONE principal is shown: only the shelves it serves, with the whole offer's digest. */
+export declare const manifestFor: (offer: Offer, principal: string, capabilities: readonly string[]) => Manifest;
+/** The capability a Business API checks for every verb of one shelf (spec P4). */
+export declare const capabilityOf: (shelfId: string) => string;
+/** One principal per shelf, so one key per shelf (spec P4; v3.2 section 12). */
+export declare const principalOf: (shelfId: string) => string;
+export type { Row };