@holokai/neuron-sdk 0.1.1 → 0.3.0

package/README.md

@@ -50,6 +50,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://api.example.com',
+  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 for enrollment/minting is a planned follow-up in `holokai-neuron-sdk` — until then, Python neurons keep using an externally supplied token.
+
+---
+
 ## Core concepts
 
 ### Capability
@@ -778,3 +815,83 @@ Heartbeats aren't reaching the gateway, so the reaper hasn't reclaimed them. Che
 ### Auth 401 on every request
 
 The `auth` callback isn't returning a valid token. If using a refresh flow, ensure the callback fetches a fresh token on each call (the SDK caches nothing — it's your callback's job).
+
+---
+
+## Releasing (maintainers)
+
+`@holokai/neuron-sdk` is published to public npm. Releases are cut from a
+monorepo-scoped git tag, and CI does the publish — there is no npm token on
+anyone's laptop and none stored in the repo.
+
+### Cut a release
+
+1. **Bump the version** in `packages/neuron-sdk/package.json`
+   (`version`). Follow semver:
+   - Pilot phase, we are in **`0.x`**. Because the protocol is still absorbing
+     pilot-developer feedback, a **breaking** change bumps the **minor**
+     (`0.2.0` → `0.3.0`); a backward-compatible change or fix bumps the
+     **patch** (`0.2.0` → `0.2.1`). This is the standard `0.x` convention and
+     is what buys us room to break things on feedback without a major bump.
+   - Hold **`1.0.0`** until the public API has survived pilot feedback and we're
+     ready to commit to "breaking changes bump the major." Jumping to `1.0.0`
+     is a stability promise, not a milestone — don't spend it early.
+2. **Commit** the bump (reference the Linear ticket) and merge to `main`.
+3. **Tag and push** from `main`:
+   ```sh
+   git tag neuron-sdk-v0.2.0        # must equal the package.json version
+   git push origin neuron-sdk-v0.2.0
+   ```
+   The tag is prefixed `neuron-sdk-v` (the Python SDK uses
+   `neuron-sdk-python-v`) so the two never collide.
+4. **`publish-neuron-sdk.yml`** fires on the tag: it asserts the tag version
+   matches `package.json`, runs the `prepublish` gate (`build` + `test`), and
+   publishes to npm. The `npm` GitHub Environment gates the publish behind a
+   **required-reviewer approval** — approve the run under Actions, and on success
+   the new version is live at
+   [`@holokai/neuron-sdk`](https://www.npmjs.com/package/@holokai/neuron-sdk).
+
+   > No `--provenance`: bigbrain is a private repo, so npm's provenance
+   > attestation (a public transparency-log link back to the source) adds little
+   > and has historically errored from private repos. Trusted-publishing auth is
+   > unaffected. Add the flag back if bigbrain ever goes public.
+
+The tag→`package.json` assertion means a mismatched tag fails **before** the
+registry is touched — npm refuses to re-upload an existing version, so there's
+no half-published state to clean up.
+
+### Publish auth: npm Trusted Publishing (one-time setup)
+
+CI authenticates to npm via **OIDC trusted publishing** — GitHub Actions
+exchanges a short-lived OIDC token for publish rights, so no long-lived
+`NPM_TOKEN` exists to leak. This mirrors the Python SDK's PyPI trusted
+publishing. It requires two one-time setups:
+
+1. **On npmjs.com** (a package admin, once): open the
+   [`@holokai/neuron-sdk`](https://www.npmjs.com/package/@holokai/neuron-sdk)
+   package → **Settings → Trusted Publisher → GitHub Actions**, and register:
+   - Organization / repository: `holok-ai/bigbrain`
+   - Workflow filename: `publish-neuron-sdk.yml`
+   - Environment: `npm`
+2. **In this repo** (once): create the **`npm`** GitHub Environment
+   (Settings → Environments). Add reviewers/branch protection here if you want a
+   manual approval gate before each publish.
+
+Until the trusted publisher is registered, the `npm publish` step fails with an
+auth error — that's the expected "not set up yet" signal, not a code bug.
+
+### Manual publish (fallback / first bootstrap)
+
+The tag flow is the norm. If you ever need to publish by hand (e.g. to bootstrap
+the very first version before trusted publishing is configured):
+
+```sh
+cd packages/neuron-sdk
+pnpm run publish:npm:dry   # inspect the tarball + files list
+pnpm run publish:npm       # runs the prepublishOnly build+test gate, then publishes
+```
+
+This uses your own `npm login` credentials and skips the CI approval gate —
+prefer the tag flow for anything a developer will consume.
+
+<!-- ci: force full build on the self-hosted runner (HOL-2028 verify); safe to remove -->

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 };