@holokai/neuron-sdk 0.2.0 → 0.4.0

package/README.md

@@ -21,6 +21,16 @@ pnpm add @holokai/neuron-sdk
 
 Runs in **Node 20+** (uses the global `fetch` and `ReadableStream`) and **modern browsers** (Chromium, Firefox, Safari latest). The package has no `node:*` imports — Holokai Desktop / Electron and the in-browser neuron-tester both consume the same SDK build.
 
+> **Gateway compatibility (protocol 1.1.0, HOL-2926).** Since protocol
+> 1.1.0 the SDK advertises each capability's contract (`description` +
+> input/output JSON Schemas) on the register frame. The gateway validates
+> register frames **strictly**, so a gateway older than HOL-2926 rejects
+> them with `INVALID_FRAME` — **deploy the gateway before publishing or
+> rolling out any 1.1.0-protocol SDK (including neuron-tester OTA)**. A
+> rejected registration leaves the SSE stream open but the neuron
+> lease-less; the SDK surfaces it via the `error` event
+> (`registration rejected by gateway: ...`) so apps can react.
+
 ---
 
 ## Quick start
@@ -29,7 +39,7 @@ Runs in **Node 20+** (uses the global `fetch` and `ReadableStream`) and **modern
 import { Neuron } from '@holokai/neuron-sdk';
 
 const neuron = new Neuron({
-  gatewayUrl: 'https://api.example.com',
+  gatewayUrl: 'https://bigbrain.holokai.dev',
   neuronId: 'my-worker-001',            // stable per process/device
   auth: () => process.env.GATEWAY_TOKEN!, // or an async refresh function
 });
@@ -50,6 +60,43 @@ process.on('SIGTERM', () => neuron.stop({ drain: true, timeoutMs: 30_000 }));
 
 ---
 
+## Authentication
+
+The `auth` callback supplies the bearer token for every POST and SSE open. How you obtain tokens depends on where the neuron runs (full model: `docs/NEURON_AUTH_SPEC.md` in the bigbrain repo):
+
+- **Desktop-embedded neurons** run under the signed-in user: exchange the user's Moku JWT for an `aud=bigbrain` token (RFC 8693) and return it from `auth`.
+- **Headless / enterprise neurons** enroll once via Moku's device flow, then mint short-lived tokens from the stored client credential — no static long-lived JWT anywhere.
+
+### Enroll (one-time, headless neurons)
+
+```bash
+npx @holokai/neuron-sdk enroll --moku-url https://moku.example \
+  --name warehouse-connector --capabilities org/acme/erp.read,org/acme/erp.write
+```
+
+Prints a verification URL + user code; an org admin approves in Moku. The client credential is written to `~/.holokai/neuron-credentials.json` (`0600`; override with `--credentials-file`). The requested capabilities are display hints for the approval screen — what the neuron may actually advertise is governed by the org's capability catalog. Polling is resilient: transient server errors (409/5xx) and network blips are retried until the device code expires; only a denial, expiry, or protocol error is terminal.
+
+Also available programmatically: `enroll(opts)` from `@holokai/neuron-sdk/auth`.
+
+### Steady state
+
+```ts
+import { Neuron } from '@holokai/neuron-sdk';
+import { createClientCredentialsAuth, defaultCredentialPath } from '@holokai/neuron-sdk/auth';
+
+const neuron = new Neuron({
+  gatewayUrl: 'https://bigbrain.holokai.dev',
+  neuronId: 'warehouse-connector-001',
+  auth: createClientCredentialsAuth(defaultCredentialPath()),
+});
+```
+
+`createClientCredentialsAuth` mints `aud=bigbrain` tokens via the OAuth2 `client_credentials` grant, caches them against the response's `expires_in` (proactive refresh, single-flight), and re-reads the credential file on `invalid_client` so an operator-rotated secret is picked up without a restart. If the credential was revoked in Moku it throws `CredentialRevokedError` — re-enroll to recover.
+
+> `@holokai/neuron-sdk/auth` is **Node-only** (it reads the credential file); the root and `./ipc` entries remain browser-clean. Python SDK parity ships in `holokai-neuron-sdk` ≥ 0.2.0 (`holokai_neuron_sdk.auth`: `holokai-neuron-sdk enroll` + `create_client_credentials_auth`) — same credential file, interchangeable across both SDKs.
+
+---
+
 ## Core concepts
 
 ### Capability
@@ -133,7 +180,7 @@ interface NeuronCommonOptions {
 
 // Convenience: SDK builds an HttpTransport for you. Most common path.
 interface NeuronOptionsWithHttp extends NeuronCommonOptions {
-  gatewayUrl: string;           // Base URL, e.g. 'https://api.example.com'
+  gatewayUrl: string;           // Base URL, e.g. 'https://bigbrain.holokai.dev'
   auth: AuthCallback;           // Token provider (see below)
   initialReconnectDelayMs?: number; // Default 500ms
   maxReconnectDelayMs?: number;     // Default 30_000 (30s)
@@ -176,6 +223,19 @@ type Handler<TInput = unknown, TOutput = unknown> = (
 
 If `inputSchema` is provided and the lease input fails validation, the handler is never called — the SDK sends a `schema-mismatch` nack automatically. Same for `outputSchema` on the return value.
 
+**Schema precedence.** For each of input and output the SDK picks exactly one validator:
+
+1. The zod schema from `defineCapability`, when the capability was registered that way. JSON Schema can't express `.refine()`, `.transform()`, or `.preprocess()`, so the zod contract stays authoritative and its transforms are what the handler sees and what goes on the wire.
+2. Otherwise the JSON Schema passed here on `CapabilityRegistration`.
+
+A capability registered with neither is not validated client-side — its handler runs on whatever arrives.
+
+The `inputSchema` / `outputSchema` that ride on the lease frame are **not** consulted. They can only ever be your own schemas handed back to you — the register frame carries no schemas, so the server's only source is the `POST /plan` handler catalog the client supplies. And the planner doesn't persist those onto task rows, so on real workflow tasks the lease frame's schemas are absent entirely; the only case where they arrive populated is the dev-only `/__dev__/inject-task` route used by neuron-tester, which echoes back what the capability registered.
+
+> **This is the only validation that runs.** The gateway's ack-time check validates against that same (empty) `lease.outputSchema`, so it does not currently catch anything. If a capability declares no schema here, its input and output are unchecked end to end.
+
+> **Note:** the Go and Python SDKs currently prefer the lease frame's schema and fall back to the registered one. TypeScript deliberately diverges here; the other two are expected to follow.
+
 ---
 
 ### `neuron.start()`
@@ -413,7 +473,7 @@ Default transport. SSE for inbound, HTTPS POST for outbound. Reconnects with exp
 import { Neuron, HttpTransport } from '@holokai/neuron-sdk';
 
 const transport = new HttpTransport({
-  gatewayUrl: 'https://api.example.com',
+  gatewayUrl: 'https://bigbrain.holokai.dev',
   neuronId: 'my-worker-001',
   auth: () => process.env.GATEWAY_TOKEN!,
   // optional:

package/dist/auth.d.mts

@@ -0,0 +1,187 @@
+/** Function returning the current bearer JWT. Called on each POST and SSE
+ *  open; can refresh tokens internally. The SDK retries once on 401, so
+ *  refreshing on 401 inside the callback is the right place to do it. */
+type AuthCallback = () => Promise<string> | string;
+/** Logger surface — minimal shape so consumers can plug in pino, console,
+ *  etc. without an interface mismatch. */
+interface NeuronLogger {
+    debug(meta: Record<string, unknown>, msg?: string): void;
+    info(meta: Record<string, unknown>, msg?: string): void;
+    warn(meta: Record<string, unknown>, msg?: string): void;
+    error(meta: Record<string, unknown>, msg?: string): void;
+}
+
+/**
+ * OAuth endpoint set resolved from RFC 8414 discovery (or the fixed
+ * fallback paths when discovery is unreachable — see `discovery.ts`).
+ */
+interface OAuthEndpoints {
+    tokenEndpoint: string;
+    deviceAuthorizationEndpoint: string;
+}
+/**
+ * The durable artifact on a neuron host: a revocable Moku OAuth client
+ * credential (never a bearer JWT). Field names mirror the wire/JSON
+ * shape so the file is greppable against Moku's own vocabulary.
+ */
+interface StoredCredential {
+    client_id: string;
+    client_secret: string;
+    token_endpoint: string;
+    moku_base_url: string;
+}
+/**
+ * How the client proves its identity to Moku's token endpoint.
+ *
+ * v1 ships `client_secret_post` only (matching Moku's discovery doc).
+ * The interface exists so `private_key_jwt` (RFC 7523, HOL-2543) can
+ * slot in later without touching `createClientCredentialsAuth` callers:
+ * a keypair-backed implementation would append a signed
+ * `client_assertion` instead of a shared secret.
+ */
+interface ClientAuthenticator {
+    /** Apply client authentication to the token-endpoint form body. */
+    apply(form: URLSearchParams): void | Promise<void>;
+}
+/** RFC 6749 §2.3.1-style shared-secret client auth, in the body. */
+declare function clientSecretPost(clientId: string, clientSecret: string): ClientAuthenticator;
+/** Successful token-endpoint response (RFC 6749 §5.1). On device-flow
+ *  redemption Moku additionally delivers the client credential — once. */
+interface TokenResponse {
+    access_token: string;
+    token_type: string;
+    expires_in: number;
+    scope?: string;
+    client_id?: string;
+    client_secret?: string;
+}
+/** Token-endpoint error (`{error, error_description}`, RFC 6749 §5.2). */
+declare class OAuthTokenError extends Error {
+    readonly error: string;
+    readonly status: number;
+    constructor(error: string, status: number, description?: string);
+}
+/**
+ * Terminal auth failure: the stored credential no longer mints (revoked,
+ * deleted, or rotated away underneath us) or does not exist. The neuron
+ * must be re-enrolled; retrying against Moku is pointless and the SDK
+ * will not loop on it.
+ */
+declare class CredentialRevokedError extends Error {
+    constructor(message: string);
+}
+/** Enrollment (device flow) failed terminally. */
+declare class EnrollmentError extends Error {
+    readonly code: 'expired_token' | 'access_denied' | 'invalid_response' | 'device_request_failed';
+    constructor(message: string, code: 'expired_token' | 'access_denied' | 'invalid_response' | 'device_request_failed');
+}
+
+interface ClientCredentialsAuthOptions {
+    fetch?: typeof fetch;
+    logger?: NeuronLogger;
+    /**
+     * Refresh this long before the token's `expires_in` elapses. The
+     * response's `expires_in` is authoritative (Moku default is 15 min,
+     * per-audience cap 1h) — never assume a lifetime.
+     */
+    refreshBufferMs?: number;
+    /**
+     * Client-auth method factory. Defaults to `client_secret_post` from the
+     * stored credential; a `private_key_jwt` implementation (HOL-2543) can
+     * be injected here without changing any other consumer code.
+     */
+    authenticator?: (credential: StoredCredential) => ClientAuthenticator;
+    /** Clock override for tests. */
+    now?: () => number;
+}
+/**
+ * Steady-state auth for enrolled (headless/enterprise) neurons: returns an
+ * `auth()` callback for `HttpTransport` that mints short-lived
+ * `aud=bigbrain` access tokens from Moku via the OAuth2 `client_credentials`
+ * grant, using the credential file written by `enroll`.
+ *
+ * Behavior:
+ * - In-memory cache driven by the response's `expires_in`, with proactive
+ *   refresh `refreshBufferMs` before expiry.
+ * - Single-flight: concurrent callers share one mint request.
+ * - On `invalid_client`, the credential file is re-read once before
+ *   failing — an operator-rotated secret is picked up without a restart.
+ * - If the re-read credential still fails (revoked/deleted client), a
+ *   `CredentialRevokedError` is thrown; the SDK's transport will not
+ *   retry-loop against Moku on it. Re-enrollment is required.
+ */
+declare function createClientCredentialsAuth(credentialPath: string, opts?: ClientCredentialsAuthOptions): AuthCallback;
+
+/** `~/.holokai/neuron-credentials.json` unless the caller overrides. */
+declare function defaultCredentialPath(): string;
+/**
+ * Read a stored credential. Returns null when the file does not exist
+ * (unenrolled); throws on a present-but-malformed file, which is an
+ * operator problem the caller must not paper over.
+ */
+declare function readCredentialFile(path: string): StoredCredential | null;
+/** Write the credential with owner-only permissions (0700 dir, 0600 file). */
+declare function writeCredentialFile(path: string, credential: StoredCredential): void;
+
+/**
+ * Resolve OAuth endpoints for a Moku base URL via RFC 8414 discovery,
+ * falling back to the fixed default paths when the metadata document is
+ * unreachable or malformed.
+ *
+ * Served endpoint URLs are re-rooted onto `mokuBaseUrl` (path is taken
+ * from the document, origin from the caller): the metadata document
+ * derives its URLs from the inbound request URL, which behind a
+ * TLS-terminating proxy can name an origin the neuron cannot reach.
+ * The caller-supplied base URL is the one address known to work.
+ */
+declare function discoverEndpoints(mokuBaseUrl: string, opts?: {
+    fetch?: typeof fetch;
+    logger?: NeuronLogger;
+}): Promise<OAuthEndpoints>;
+
+interface EnrollOptions {
+    /** Moku base URL — the only required config (endpoints are discovered). */
+    mokuBaseUrl: string;
+    /** Display name shown to the approving admin. Required by Moku. */
+    clientName: string;
+    /** Display hint for the approval screen; defaults to `os.hostname()`. */
+    hostname?: string;
+    /**
+     * Capability types this neuron intends to serve — display hints for the
+     * approval screen ONLY. Authorization comes from the org's capability
+     * catalog, not from this list (requested ≠ granted).
+     */
+    capabilityTypes?: string[];
+    /** Where to persist the credential. Default: `~/.holokai/neuron-credentials.json`. */
+    credentialPath?: string;
+    fetch?: typeof fetch;
+    logger?: NeuronLogger;
+    /** Where user-facing lines (verification URI + user code) go. Default: console.log. */
+    out?: (line: string) => void;
+    /** Sleep override for tests. */
+    sleep?: (ms: number) => Promise<void>;
+}
+interface EnrollResult {
+    status: 'already-enrolled' | 'enrolled';
+    clientId: string;
+    credentialPath: string;
+    /** Bootstrap token from the redemption response (only when freshly enrolled). */
+    accessToken?: string;
+    expiresIn?: number;
+}
+/**
+ * One-time enrollment of a headless neuron via Moku's RFC 8628 device
+ * authorization grant.
+ *
+ * Flow: start a device authorization → print the verification URI +
+ * user code (container-log friendly) → poll the token endpoint until an
+ * org ADMIN approves in Moku → persist the client credential delivered
+ * in the redemption token response (delivered exactly once).
+ *
+ * Idempotent: if a credential file already exists and still mints, this
+ * is a no-op reporting `already-enrolled`. A revoked existing credential
+ * falls through to a fresh enrollment.
+ */
+declare function enroll(opts: EnrollOptions): Promise<EnrollResult>;
+
+export { type ClientAuthenticator, type ClientCredentialsAuthOptions, CredentialRevokedError, type EnrollOptions, type EnrollResult, EnrollmentError, type OAuthEndpoints, OAuthTokenError, type StoredCredential, type TokenResponse, clientSecretPost, createClientCredentialsAuth, defaultCredentialPath, discoverEndpoints, enroll, readCredentialFile, writeCredentialFile };

package/dist/auth.d.ts

@@ -0,0 +1,187 @@
+/** Function returning the current bearer JWT. Called on each POST and SSE
+ *  open; can refresh tokens internally. The SDK retries once on 401, so
+ *  refreshing on 401 inside the callback is the right place to do it. */
+type AuthCallback = () => Promise<string> | string;
+/** Logger surface — minimal shape so consumers can plug in pino, console,
+ *  etc. without an interface mismatch. */
+interface NeuronLogger {
+    debug(meta: Record<string, unknown>, msg?: string): void;
+    info(meta: Record<string, unknown>, msg?: string): void;
+    warn(meta: Record<string, unknown>, msg?: string): void;
+    error(meta: Record<string, unknown>, msg?: string): void;
+}
+
+/**
+ * OAuth endpoint set resolved from RFC 8414 discovery (or the fixed
+ * fallback paths when discovery is unreachable — see `discovery.ts`).
+ */
+interface OAuthEndpoints {
+    tokenEndpoint: string;
+    deviceAuthorizationEndpoint: string;
+}
+/**
+ * The durable artifact on a neuron host: a revocable Moku OAuth client
+ * credential (never a bearer JWT). Field names mirror the wire/JSON
+ * shape so the file is greppable against Moku's own vocabulary.
+ */
+interface StoredCredential {
+    client_id: string;
+    client_secret: string;
+    token_endpoint: string;
+    moku_base_url: string;
+}
+/**
+ * How the client proves its identity to Moku's token endpoint.
+ *
+ * v1 ships `client_secret_post` only (matching Moku's discovery doc).
+ * The interface exists so `private_key_jwt` (RFC 7523, HOL-2543) can
+ * slot in later without touching `createClientCredentialsAuth` callers:
+ * a keypair-backed implementation would append a signed
+ * `client_assertion` instead of a shared secret.
+ */
+interface ClientAuthenticator {
+    /** Apply client authentication to the token-endpoint form body. */
+    apply(form: URLSearchParams): void | Promise<void>;
+}
+/** RFC 6749 §2.3.1-style shared-secret client auth, in the body. */
+declare function clientSecretPost(clientId: string, clientSecret: string): ClientAuthenticator;
+/** Successful token-endpoint response (RFC 6749 §5.1). On device-flow
+ *  redemption Moku additionally delivers the client credential — once. */
+interface TokenResponse {
+    access_token: string;
+    token_type: string;
+    expires_in: number;
+    scope?: string;
+    client_id?: string;
+    client_secret?: string;
+}
+/** Token-endpoint error (`{error, error_description}`, RFC 6749 §5.2). */
+declare class OAuthTokenError extends Error {
+    readonly error: string;
+    readonly status: number;
+    constructor(error: string, status: number, description?: string);
+}
+/**
+ * Terminal auth failure: the stored credential no longer mints (revoked,
+ * deleted, or rotated away underneath us) or does not exist. The neuron
+ * must be re-enrolled; retrying against Moku is pointless and the SDK
+ * will not loop on it.
+ */
+declare class CredentialRevokedError extends Error {
+    constructor(message: string);
+}
+/** Enrollment (device flow) failed terminally. */
+declare class EnrollmentError extends Error {
+    readonly code: 'expired_token' | 'access_denied' | 'invalid_response' | 'device_request_failed';
+    constructor(message: string, code: 'expired_token' | 'access_denied' | 'invalid_response' | 'device_request_failed');
+}
+
+interface ClientCredentialsAuthOptions {
+    fetch?: typeof fetch;
+    logger?: NeuronLogger;
+    /**
+     * Refresh this long before the token's `expires_in` elapses. The
+     * response's `expires_in` is authoritative (Moku default is 15 min,
+     * per-audience cap 1h) — never assume a lifetime.
+     */
+    refreshBufferMs?: number;
+    /**
+     * Client-auth method factory. Defaults to `client_secret_post` from the
+     * stored credential; a `private_key_jwt` implementation (HOL-2543) can
+     * be injected here without changing any other consumer code.
+     */
+    authenticator?: (credential: StoredCredential) => ClientAuthenticator;
+    /** Clock override for tests. */
+    now?: () => number;
+}
+/**
+ * Steady-state auth for enrolled (headless/enterprise) neurons: returns an
+ * `auth()` callback for `HttpTransport` that mints short-lived
+ * `aud=bigbrain` access tokens from Moku via the OAuth2 `client_credentials`
+ * grant, using the credential file written by `enroll`.
+ *
+ * Behavior:
+ * - In-memory cache driven by the response's `expires_in`, with proactive
+ *   refresh `refreshBufferMs` before expiry.
+ * - Single-flight: concurrent callers share one mint request.
+ * - On `invalid_client`, the credential file is re-read once before
+ *   failing — an operator-rotated secret is picked up without a restart.
+ * - If the re-read credential still fails (revoked/deleted client), a
+ *   `CredentialRevokedError` is thrown; the SDK's transport will not
+ *   retry-loop against Moku on it. Re-enrollment is required.
+ */
+declare function createClientCredentialsAuth(credentialPath: string, opts?: ClientCredentialsAuthOptions): AuthCallback;
+
+/** `~/.holokai/neuron-credentials.json` unless the caller overrides. */
+declare function defaultCredentialPath(): string;
+/**
+ * Read a stored credential. Returns null when the file does not exist
+ * (unenrolled); throws on a present-but-malformed file, which is an
+ * operator problem the caller must not paper over.
+ */
+declare function readCredentialFile(path: string): StoredCredential | null;
+/** Write the credential with owner-only permissions (0700 dir, 0600 file). */
+declare function writeCredentialFile(path: string, credential: StoredCredential): void;
+
+/**
+ * Resolve OAuth endpoints for a Moku base URL via RFC 8414 discovery,
+ * falling back to the fixed default paths when the metadata document is
+ * unreachable or malformed.
+ *
+ * Served endpoint URLs are re-rooted onto `mokuBaseUrl` (path is taken
+ * from the document, origin from the caller): the metadata document
+ * derives its URLs from the inbound request URL, which behind a
+ * TLS-terminating proxy can name an origin the neuron cannot reach.
+ * The caller-supplied base URL is the one address known to work.
+ */
+declare function discoverEndpoints(mokuBaseUrl: string, opts?: {
+    fetch?: typeof fetch;
+    logger?: NeuronLogger;
+}): Promise<OAuthEndpoints>;
+
+interface EnrollOptions {
+    /** Moku base URL — the only required config (endpoints are discovered). */
+    mokuBaseUrl: string;
+    /** Display name shown to the approving admin. Required by Moku. */
+    clientName: string;
+    /** Display hint for the approval screen; defaults to `os.hostname()`. */
+    hostname?: string;
+    /**
+     * Capability types this neuron intends to serve — display hints for the
+     * approval screen ONLY. Authorization comes from the org's capability
+     * catalog, not from this list (requested ≠ granted).
+     */
+    capabilityTypes?: string[];
+    /** Where to persist the credential. Default: `~/.holokai/neuron-credentials.json`. */
+    credentialPath?: string;
+    fetch?: typeof fetch;
+    logger?: NeuronLogger;
+    /** Where user-facing lines (verification URI + user code) go. Default: console.log. */
+    out?: (line: string) => void;
+    /** Sleep override for tests. */
+    sleep?: (ms: number) => Promise<void>;
+}
+interface EnrollResult {
+    status: 'already-enrolled' | 'enrolled';
+    clientId: string;
+    credentialPath: string;
+    /** Bootstrap token from the redemption response (only when freshly enrolled). */
+    accessToken?: string;
+    expiresIn?: number;
+}
+/**
+ * One-time enrollment of a headless neuron via Moku's RFC 8628 device
+ * authorization grant.
+ *
+ * Flow: start a device authorization → print the verification URI +
+ * user code (container-log friendly) → poll the token endpoint until an
+ * org ADMIN approves in Moku → persist the client credential delivered
+ * in the redemption token response (delivered exactly once).
+ *
+ * Idempotent: if a credential file already exists and still mints, this
+ * is a no-op reporting `already-enrolled`. A revoked existing credential
+ * falls through to a fresh enrollment.
+ */
+declare function enroll(opts: EnrollOptions): Promise<EnrollResult>;
+
+export { type ClientAuthenticator, type ClientCredentialsAuthOptions, CredentialRevokedError, type EnrollOptions, type EnrollResult, EnrollmentError, type OAuthEndpoints, OAuthTokenError, type StoredCredential, type TokenResponse, clientSecretPost, createClientCredentialsAuth, defaultCredentialPath, discoverEndpoints, enroll, readCredentialFile, writeCredentialFile };