@xtrable-ltd/nanoesis 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Xtrable Ltd
+
+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

@@ -0,0 +1,73 @@
+# @xtrable-ltd/nanoesis
+
+A static-first **publishing compiler**: author content in a calm editor, compile it to plain
+static HTML at publish time, and ship files with no runtime, no server, and nothing of the
+tooling surviving into production.
+
+This one package contains everything an adopter needs (DESIGN §11c): the engine, the
+mountable editor API, the storage / image / auth adapters, and the editor UI bundle, each
+reachable as a subpath import.
+
+```bash
+npm install @xtrable-ltd/nanoesis
+```
+
+## What you import
+
+```ts
+import { compile, type BlobStore }     from '@xtrable-ltd/nanoesis';                 // the engine
+import { handleApi, type ApiDeps }     from '@xtrable-ltd/nanoesis/editor-api';       // mount in your host
+import { FsBlobStore, FsArtifactSink } from '@xtrable-ltd/nanoesis/adapter-fs';       // a local-folder store
+import { createSharpEncoder }          from '@xtrable-ltd/nanoesis/adapter-sharp';    // responsive <picture>
+import { ShellPreBuildHook }           from '@xtrable-ltd/nanoesis/adapter-shell';    // pre-publish build hook
+import { editorDist }                  from '@xtrable-ltd/nanoesis/editor';           // path to the SPA you serve
+```
+
+Also available: `/adapter-azure-blob`, `/adapter-cloudflare`, `/adapter-local-jwt`,
+`/adapter-trusted-header`.
+
+## The whole integration
+
+A nanoesis host is two things: a **store** the editor reads and writes through (`get` /
+`put` / `delete`), and a **publish** step that compiles the working files to a static site.
+Mount the API on any Node server and serve the bundled editor:
+
+```ts
+import { createServer } from 'node:http';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { handleApi } from '@xtrable-ltd/nanoesis/editor-api';
+import { IndexedStore, contentTypeFor, publishSite } from '@xtrable-ltd/nanoesis';
+import { FsBlobStore, FsArtifactSink } from '@xtrable-ltd/nanoesis/adapter-fs';
+import { createSharpEncoder } from '@xtrable-ltd/nanoesis/adapter-sharp';
+import { editorDist } from '@xtrable-ltd/nanoesis/editor';
+
+const store = new IndexedStore(new FsBlobStore('site')); // your content lives in ./site
+const sink = new FsArtifactSink('published'); // the compiled static site lands in ./published
+
+const deps = {
+  store,
+  identity: { authenticate: async () => ({ userId: 'local', username: 'local', roles: ['admin'] }) },
+  publish: async () => {
+    await sink.wipe();
+    return publishSite(store, sink, { imageEncoder: createSharpEncoder() });
+  },
+};
+
+createServer((req, res) => {
+  /* /api/* -> handleApi(deps, ...); everything else -> serve files from editorDist */
+}).listen(7071);
+```
+
+A complete, runnable version of this is in the repo's `examples/minimal-host`. For a real
+deployment swap `FsBlobStore` for `/adapter-azure-blob` (or your own `get`/`put`/`delete`
+store), and the local-admin stub for `/adapter-local-jwt` or `/adapter-trusted-header`.
+
+## How it ships
+
+- **The editor** (`editorDist`) is a static SPA you serve from your host.
+- **The published site** (whatever `publishSite` writes to your sink) is plain static files;
+  point any static host or CDN at them. Production runs no nanoesis code.
+
+MIT © Xtrable Ltd.

package/dist/adapter-azure-blob.d.ts

@@ -0,0 +1,97 @@
+import { ContainerClient } from '@azure/storage-blob';
+import { BlobStore, ArtifactSink } from '@nanoesis/engine';
+export { contentTypeFor } from '@nanoesis/engine';
+
+/**
+ * The narrow blob-container seam the adapters depend on. It is the *only* surface the
+ * Azure SDK is wrapped behind ({@link AzureBlobContainer}), which keeps the SDK out of
+ * the adapters' logic and lets every path-mapping rule be unit-tested against the
+ * in-memory container below, no real or emulated blob store in the default suite
+ * (CLAUDE.md §5). Names are flat blob names (forward slashes, no leading slash).
+ */
+interface BlobContainer {
+    /** Every blob name beginning with `prefix` ("" lists the whole container). */
+    list(prefix: string): Promise<readonly string[]>;
+    /** A blob's bytes, or null if it does not exist. */
+    read(name: string): Promise<Uint8Array | null>;
+    /** Create or overwrite a blob with the given bytes and content type. */
+    write(name: string, data: Uint8Array, contentType: string): Promise<void>;
+    /** Delete a blob; a missing blob is a no-op (idempotent). */
+    remove(name: string): Promise<void>;
+}
+/**
+ * An in-memory {@link BlobContainer} backed by a name→bytes map. The test double for
+ * the blob adapters, the LSP guarantee that the real Azure container behaves the same.
+ */
+declare class InMemoryBlobContainer implements BlobContainer {
+    private readonly blobs;
+    constructor(seed?: Readonly<Record<string, Uint8Array | string>>);
+    list(prefix: string): Promise<readonly string[]>;
+    read(name: string): Promise<Uint8Array | null>;
+    write(name: string, data: Uint8Array): Promise<void>;
+    remove(name: string): Promise<void>;
+    /** Test helper: the current blob names. */
+    get names(): readonly string[];
+}
+
+/**
+ * The real {@link BlobContainer}, wrapping `@azure/storage-blob`. This is the *only*
+ * file in the adapter that touches the SDK (CLAUDE.md §3, concretes injected via a
+ * narrow seam); everything else is pure logic tested against {@link InMemoryBlobContainer}.
+ * It talks to a real Azure account or to **Azurite** locally, unchanged, the
+ * `UseDevelopmentStorage=true` connection string points at the emulator.
+ */
+declare class AzureBlobContainer implements BlobContainer {
+    private readonly client;
+    constructor(client: ContainerClient);
+    /** Build from a connection string (e.g. `UseDevelopmentStorage=true` for Azurite). */
+    static fromConnectionString(connectionString: string, containerName: string): AzureBlobContainer;
+    /** Create the container if it does not exist (idempotent host start-up step). */
+    ensureContainer(): Promise<void>;
+    list(prefix: string): Promise<readonly string[]>;
+    read(name: string): Promise<Uint8Array | null>;
+    write(name: string, data: Uint8Array, contentType: string): Promise<void>;
+    remove(name: string): Promise<void>;
+}
+
+/**
+ * The engine's {@link BlobStore} (get/put/delete, DESIGN §11c) over a {@link BlobContainer}.
+ * This is the adopter's storage primitive the index-backed working store (and the publish
+ * sink) run on, and it works over the real {@link AzureBlobContainer} in production or the
+ * in-memory container in tests (LSP). Keys are POSIX-style; `put` stamps a content type
+ * from the key's extension so a published blob serves correctly as a static-website file.
+ */
+declare class BlobContainerStore implements BlobStore {
+    private readonly container;
+    constructor(container: BlobContainer);
+    get(key: string): Promise<Uint8Array | undefined>;
+    put(key: string, bytes: Uint8Array): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+
+/**
+ * The **published store** over an Azure Blob container (DESIGN §11, §11b, §11c): the
+ * publish pipeline's {@link ArtifactSink}. Publish only writes now, clearing the target
+ * is the adopter's job (DESIGN §11c), so {@link wipe} (delete every blob in the container)
+ * is the host's own pre-clear that it calls before a wipe-and-reupload republish. Each
+ * artifact is uploaded with a content type inferred from its path so the container can be
+ * served as a static website (Azurite's `$web`/static-site endpoint locally).
+ */
+declare class BlobArtifactSink implements ArtifactSink {
+    private readonly container;
+    constructor(container: BlobContainer);
+    wipe(): Promise<void>;
+    write(path: string, contents: string | Uint8Array): Promise<void>;
+}
+
+/**
+ * Pure path/name helper for the blob adapters. Blob storage is a *flat* namespace, a blob
+ * is just a name like "content/blog/post.json", so the only mapping the SDK glue needs is
+ * to normalise a site-relative path into a blob name. Enumeration lives in the engine's
+ * content index (DESIGN §11d), not here. Keeping this pure means it is unit-tested without
+ * a real (or emulated) blob store; the SDK glue stays thin (CLAUDE.md §5).
+ */
+/** Normalise a site path to a blob name: forward slashes, no leading/trailing slash. */
+declare function normalizeBlobName(path: string): string;
+
+export { AzureBlobContainer, BlobArtifactSink, type BlobContainer, BlobContainerStore, InMemoryBlobContainer, normalizeBlobName };

package/dist/adapter-azure-blob.js

@@ -0,0 +1,127 @@
+import {
+  contentTypeFor
+} from "./chunk-G2UEZTYC.js";
+
+// ../../adapters/azure-blob/src/container.ts
+var InMemoryBlobContainer = class {
+  blobs = /* @__PURE__ */ new Map();
+  constructor(seed = {}) {
+    for (const [name, value] of Object.entries(seed)) {
+      this.blobs.set(name, typeof value === "string" ? new TextEncoder().encode(value) : value);
+    }
+  }
+  async list(prefix) {
+    const names = [];
+    for (const name of this.blobs.keys()) {
+      if (name.startsWith(prefix)) names.push(name);
+    }
+    return names.sort();
+  }
+  async read(name) {
+    return this.blobs.get(name) ?? null;
+  }
+  async write(name, data) {
+    this.blobs.set(name, data);
+  }
+  async remove(name) {
+    this.blobs.delete(name);
+  }
+  /** Test helper: the current blob names. */
+  get names() {
+    return [...this.blobs.keys()].sort();
+  }
+};
+
+// ../../adapters/azure-blob/src/azure-container.ts
+import { BlobServiceClient } from "@azure/storage-blob";
+function isNotFound(error) {
+  return typeof error === "object" && error !== null && "statusCode" in error && error.statusCode === 404;
+}
+var AzureBlobContainer = class _AzureBlobContainer {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /** Build from a connection string (e.g. `UseDevelopmentStorage=true` for Azurite). */
+  static fromConnectionString(connectionString, containerName) {
+    const service = BlobServiceClient.fromConnectionString(connectionString);
+    return new _AzureBlobContainer(service.getContainerClient(containerName));
+  }
+  /** Create the container if it does not exist (idempotent host start-up step). */
+  async ensureContainer() {
+    await this.client.createIfNotExists();
+  }
+  async list(prefix) {
+    const names = [];
+    for await (const blob of this.client.listBlobsFlat({ prefix })) {
+      names.push(blob.name);
+    }
+    return names;
+  }
+  async read(name) {
+    try {
+      const buffer = await this.client.getBlockBlobClient(name).downloadToBuffer();
+      return new Uint8Array(buffer);
+    } catch (error) {
+      if (isNotFound(error)) return null;
+      throw error;
+    }
+  }
+  async write(name, data, contentType) {
+    await this.client.getBlockBlobClient(name).uploadData(Buffer.from(data), {
+      blobHTTPHeaders: { blobContentType: contentType }
+    });
+  }
+  async remove(name) {
+    await this.client.getBlockBlobClient(name).deleteIfExists();
+  }
+};
+
+// ../../adapters/azure-blob/src/paths.ts
+function normalizeBlobName(path) {
+  return path.replace(/\\/g, "/").replace(/^\.\//, "").replace(/^\/+/, "").replace(/\/+$/, "");
+}
+
+// ../../adapters/azure-blob/src/blob-container-store.ts
+var BlobContainerStore = class {
+  constructor(container) {
+    this.container = container;
+  }
+  container;
+  async get(key) {
+    return await this.container.read(normalizeBlobName(key)) ?? void 0;
+  }
+  async put(key, bytes) {
+    const name = normalizeBlobName(key);
+    await this.container.write(name, bytes, contentTypeFor(name));
+  }
+  async delete(key) {
+    await this.container.remove(normalizeBlobName(key));
+  }
+};
+
+// ../../adapters/azure-blob/src/blob-sink.ts
+var BlobArtifactSink = class {
+  constructor(container) {
+    this.container = container;
+  }
+  container;
+  async wipe() {
+    for (const name of await this.container.list("")) {
+      await this.container.remove(name);
+    }
+  }
+  async write(path, contents) {
+    const name = normalizeBlobName(path);
+    const data = typeof contents === "string" ? new TextEncoder().encode(contents) : contents;
+    await this.container.write(name, data, contentTypeFor(name));
+  }
+};
+export {
+  AzureBlobContainer,
+  BlobArtifactSink,
+  BlobContainerStore,
+  InMemoryBlobContainer,
+  contentTypeFor,
+  normalizeBlobName
+};

package/dist/adapter-cloudflare.d.ts

@@ -0,0 +1,28 @@
+import { PurgeService } from '@nanoesis/engine';
+
+interface CloudflarePurgeConfig {
+    /** The Cloudflare zone ID fronting the published site. */
+    readonly zoneId: string;
+    /** A scoped API token with the "Cache Purge" permission for the zone. */
+    readonly apiToken: string;
+    /** Injected for tests; defaults to the global `fetch`. */
+    readonly fetch?: typeof fetch;
+    /** Override the API base (defaults to the public Cloudflare endpoint). */
+    readonly baseUrl?: string;
+}
+/**
+ * A {@link PurgeService} that invalidates an entire Cloudflare zone after a publish
+ * (DESIGN §11, Phase 1 purges everything, no per-path batching). It is a single HTTP
+ * call (`POST /zones/{zone}/purge_cache` with `purge_everything: true`), so it needs no
+ * SDK; `fetch` is injected for hermetic testing. The host wires this in production; the
+ * local example uses the engine's no-op purge instead (no Cloudflare account needed).
+ */
+declare class CloudflarePurge implements PurgeService {
+    private readonly config;
+    private readonly fetchFn;
+    private readonly endpoint;
+    constructor(config: CloudflarePurgeConfig);
+    purgeAll(): Promise<void>;
+}
+
+export { CloudflarePurge, type CloudflarePurgeConfig };

package/dist/adapter-cloudflare.js

@@ -0,0 +1,32 @@
+// ../../adapters/cloudflare/src/cloudflare-purge.ts
+var CloudflarePurge = class {
+  constructor(config) {
+    this.config = config;
+    this.fetchFn = config.fetch ?? fetch;
+    const base = config.baseUrl ?? "https://api.cloudflare.com/client/v4";
+    this.endpoint = `${base}/zones/${config.zoneId}/purge_cache`;
+  }
+  config;
+  fetchFn;
+  endpoint;
+  async purgeAll() {
+    const response = await this.fetchFn(this.endpoint, {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${this.config.apiToken}`,
+        "content-type": "application/json"
+      },
+      body: JSON.stringify({ purge_everything: true })
+    });
+    if (!response.ok) {
+      throw new Error(`Cloudflare purge failed: HTTP ${response.status} ${response.statusText}`);
+    }
+    const body = await response.json();
+    if (body.success !== true) {
+      throw new Error(`Cloudflare purge rejected: ${JSON.stringify(body.errors ?? body)}`);
+    }
+  }
+};
+export {
+  CloudflarePurge
+};

package/dist/adapter-fs.d.ts

@@ -0,0 +1,38 @@
+import { BlobStore, ArtifactSink } from '@nanoesis/engine';
+
+/**
+ * Filesystem implementation of the engine's {@link BlobStore} port (DESIGN §11c): get /
+ * put / delete over a local directory, the no-cloud storage primitive for local
+ * development. Keys are POSIX-style site-relative paths mapped onto files under `root`
+ * (e.g. "content/blog/post.json" → `<root>/content/blog/post.json`); the index-backed
+ * working store runs on top of this exactly as it does on the blob adapter (LSP).
+ */
+declare class FsBlobStore implements BlobStore {
+    private readonly root;
+    constructor(root: string);
+    private resolve;
+    get(key: string): Promise<Uint8Array | undefined>;
+    put(key: string, bytes: Uint8Array): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+
+/**
+ * Filesystem implementation of the engine's {@link ArtifactSink} port (DESIGN §3/§11c):
+ * the publish pipeline emits every compiled artifact through {@link write}, here onto a
+ * local output directory. It is the no-cloud counterpart of the blob sink, the same
+ * behaviour (LSP), used by `@nanoesis/host-mcp` to publish a site locally. Paths are
+ * POSIX-style and relative to `root` (e.g. "blog/first/index.html").
+ *
+ * Publish only writes (DESIGN §11c); clearing the target is the host's job, so {@link wipe}
+ * is offered for the host to call before a wipe-and-republish, not part of the port.
+ */
+declare class FsArtifactSink implements ArtifactSink {
+    private readonly root;
+    constructor(root: string);
+    private resolve;
+    write(path: string, contents: string | Uint8Array): Promise<void>;
+    /** Empty the output directory before a republish. A missing directory is a no-op. */
+    wipe(): Promise<void>;
+}
+
+export { FsArtifactSink, FsBlobStore };

package/dist/adapter-fs.js

@@ -0,0 +1,54 @@
+// ../../adapters/fs/src/fs-blob-store.ts
+import { mkdir, readFile, rm, writeFile } from "fs/promises";
+import { dirname, join } from "path";
+var FsBlobStore = class {
+  constructor(root) {
+    this.root = root;
+  }
+  root;
+  resolve(key) {
+    return join(this.root, ...key.split("/").filter((segment) => segment !== ""));
+  }
+  async get(key) {
+    try {
+      return new Uint8Array(await readFile(this.resolve(key)));
+    } catch (error) {
+      if (error.code === "ENOENT") return void 0;
+      throw error;
+    }
+  }
+  async put(key, bytes) {
+    const dest = this.resolve(key);
+    await mkdir(dirname(dest), { recursive: true });
+    await writeFile(dest, bytes);
+  }
+  async delete(key) {
+    await rm(this.resolve(key), { force: true });
+  }
+};
+
+// ../../adapters/fs/src/fs-artifact-sink.ts
+import { mkdir as mkdir2, rm as rm2, writeFile as writeFile2 } from "fs/promises";
+import { dirname as dirname2, join as join2 } from "path";
+var FsArtifactSink = class {
+  constructor(root) {
+    this.root = root;
+  }
+  root;
+  resolve(path) {
+    return join2(this.root, ...path.split("/").filter((segment) => segment !== ""));
+  }
+  async write(path, contents) {
+    const dest = this.resolve(path);
+    await mkdir2(dirname2(dest), { recursive: true });
+    await writeFile2(dest, contents);
+  }
+  /** Empty the output directory before a republish. A missing directory is a no-op. */
+  async wipe() {
+    await rm2(this.root, { recursive: true, force: true });
+  }
+};
+export {
+  FsArtifactSink,
+  FsBlobStore
+};

package/dist/adapter-local-jwt.d.ts

@@ -0,0 +1,205 @@
+import { Role, IdentityProvider, AuthEndpoints, UserAdminEndpoints } from '@nanoesis/engine';
+
+/**
+ * One user record. Every field is owned by the adapter, a custom UserStore must
+ * round-trip them all. `loginCount` is the revocation counter (DESIGN §11): every
+ * login/logout bumps it, and a JWT carrying a stale count is rejected; one cheap
+ * UserStore read per request gets per-user revocation without a SessionStore.
+ *
+ * `failedAttempts` + `lockedUntil` drive the brute-force lockout (3 / 1 min per
+ * DESIGN §11); they live alongside the credential so a custom store doesn't have
+ * to ship its own attempt-tracking surface.
+ */
+interface UserRecord {
+    /** Stable identifier (set once at create time, never reused). */
+    readonly id: string;
+    /** Login handle the user types. Case-insensitive lookups recommended at the store level. */
+    readonly username: string;
+    /**
+     * Optional display name (bylines, account menu). Absent means "use {@link username}".
+     * Stored trimmed; blank is normalised to absent by the provider.
+     */
+    readonly displayName?: string;
+    readonly roles: readonly Role[];
+    /** scrypt hash; opaque to consumers, produced by the adapter's `password` module. */
+    readonly passwordHash: string;
+    /** Revocation counter, bumped on every login and logout. */
+    readonly loginCount: number;
+    /** Consecutive failed login attempts since the last success. */
+    readonly failedAttempts: number;
+    /** Epoch ms; when set and in the future, the account is locked out. */
+    readonly lockedUntil?: number;
+    /**
+     * Personal-access-token revocation counter (DESIGN §14). PATs (the MCP HTTP transport)
+     * carry this value; bumping it revokes every PAT for the user, independent of the login
+     * session (so editor logins never invalidate a PAT). Absent is treated as 0.
+     */
+    readonly patVersion?: number;
+    /** Epoch ms; record creation time. */
+    readonly createdAt: number;
+    /** Epoch ms; last write time. */
+    readonly updatedAt: number;
+}
+/**
+ * The credential store the local-JWT provider talks to. A user supplies a concrete
+ * implementation (file-backed is shipped; bring your own for blob/cosmos/sql). The
+ * port is deliberately small, every method maps onto one auth operation.
+ */
+interface UserStore {
+    /** True when no records exist; drives the first-run-becomes-admin path (DESIGN §11). */
+    isEmpty(): Promise<boolean>;
+    getByUsername(username: string): Promise<UserRecord | null>;
+    getById(id: string): Promise<UserRecord | null>;
+    /** Insert or replace by `id`. */
+    put(user: UserRecord): Promise<void>;
+    remove(id: string): Promise<void>;
+    /** All records, in deterministic order, for admin "list users" tooling. */
+    list(): Promise<readonly UserRecord[]>;
+}
+/**
+ * An ephemeral in-process {@link UserStore}. Useful for tests and ephemeral examples;
+ * never persistent. Lookups by username are case-insensitive.
+ */
+declare class InMemoryUserStore implements UserStore {
+    private readonly byId;
+    isEmpty(): Promise<boolean>;
+    getByUsername(username: string): Promise<UserRecord | null>;
+    getById(id: string): Promise<UserRecord | null>;
+    put(user: UserRecord): Promise<void>;
+    remove(id: string): Promise<void>;
+    list(): Promise<readonly UserRecord[]>;
+}
+/**
+ * A JSON-file {@link UserStore} for the local example and small self-hosted deploys.
+ * The whole file is read and rewritten atomically (write to `.tmp`, rename) so a crash
+ * mid-write leaves the previous good file. Suitable up to "tens of users on one
+ * process"; production deploys with real persistence should bring their own
+ * implementation of {@link UserStore}.
+ *
+ * The file is `{"users": UserRecord[]}`, versionable JSON, hand-editable in a pinch.
+ */
+declare class FileUserStore implements UserStore {
+    private readonly path;
+    constructor(path: string);
+    private load;
+    private save;
+    isEmpty(): Promise<boolean>;
+    getByUsername(username: string): Promise<UserRecord | null>;
+    getById(id: string): Promise<UserRecord | null>;
+    put(user: UserRecord): Promise<void>;
+    remove(id: string): Promise<void>;
+    list(): Promise<readonly UserRecord[]>;
+}
+
+/** Thrown when a password is rejected at hash time (before the work). */
+declare class WeakPasswordError extends Error {
+    constructor(reason: string);
+}
+/**
+ * Hash a password with scrypt and return a self-describing string of the form
+ * `scrypt$1$<base64 salt>$<base64 hash>`. Re-derivable later by `verifyPassword`
+ * with no other state, every parameter the hash needs is encoded in the prefix.
+ *
+ * Rejects an empty password (a kindness to the caller; the routes layer is expected to
+ * also require a non-empty password on the way in). No length floor is imposed, the
+ * deployment owns its password policy.
+ */
+declare function hashPassword(password: string): Promise<string>;
+/**
+ * Constant-time check of `password` against an `encoded` hash produced by
+ * {@link hashPassword}. Returns false on every shape of mismatch, wrong password,
+ * truncated/garbage hash string, unknown version, so the caller never has to branch
+ * on "is this hash valid". Constant time matters here: it's the login hot path.
+ */
+declare function verifyPassword(password: string, encoded: string): Promise<boolean>;
+
+/**
+ * The JWT payload nanoesis issues. Compact on purpose, every byte is sent on every
+ * authenticated request. `lc` is the loginCount revocation counter (DESIGN §11),
+ * compared against the user record on `authenticate` and `refresh`.
+ */
+interface JwtPayload {
+    /** Subject: the user record id. */
+    readonly sub: string;
+    /** Roles snapshot at issue time. */
+    readonly roles: readonly Role[];
+    /** loginCount when the token was issued, revocation handle for session tokens. */
+    readonly lc: number;
+    /** Issued-at epoch seconds. */
+    readonly iat: number;
+    /** Expiry epoch seconds. */
+    readonly exp: number;
+    /** Marks a personal access token (DESIGN §14): validated against `patVersion`, not `lc`. */
+    readonly pat?: true;
+    /** patVersion at issue time (PATs only); the revocation handle independent of loginCount. */
+    readonly pv?: number;
+}
+/** Distinct failure modes for `verifyJwt`, the caller maps them to HTTP status. */
+type JwtVerifyError = 'malformed' | 'bad-signature' | 'expired';
+type JwtVerifyResult = {
+    readonly ok: true;
+    readonly payload: JwtPayload;
+} | {
+    readonly ok: false;
+    readonly reason: JwtVerifyError;
+};
+/**
+ * Sign a JWT (compact serialization, HS256). Standard layout
+ * `base64url(header).base64url(payload).base64url(HMAC-SHA256(header.payload))`, no
+ * external dep, just `node:crypto`. The secret is opaque bytes; pick at least 32 of
+ * them from a CSPRNG.
+ */
+declare function signJwt(payload: JwtPayload, secret: string | Buffer): string;
+/**
+ * Verify a JWT and return either the payload or a structured reason for the rejection.
+ * Never throws on bad input, a malformed token returns `{ ok: false, reason: 'malformed' }`,
+ * which matches how the rest of the host handles boundary failures (data, not exceptions).
+ *
+ * `nowSeconds` is injected for tests so we can verify the expiry boundary without
+ * sleeping, and so the rest of the adapter doesn't need a Clock port.
+ */
+declare function verifyJwt(token: string, secret: string | Buffer, nowSeconds?: number): JwtVerifyResult;
+
+/**
+ * Configuration for {@link createLocalJwtAuth}. The defaults match DESIGN §11, 10-min
+ * access tokens forcing a re-check of the loginCount, 3 failed attempts before a
+ * 1-minute lockout, and bumping loginCount on every login/logout so a previously-
+ * issued token dies the next time its owner logs in.
+ *
+ * `now` and `newId` are injected for tests so the lockout windows and id generation
+ * are deterministic; production should leave them at their defaults.
+ */
+interface LocalJwtConfig {
+    readonly users: UserStore;
+    /** HMAC-SHA256 secret. At least 32 bytes of CSPRNG output. */
+    readonly signingSecret: string | Buffer;
+    /** Access-token TTL in seconds. Default 600 (10 min). */
+    readonly accessTokenTtlSeconds?: number;
+    /** Personal-access-token (PAT) TTL in seconds. Long by design, a PAT lives in a client
+     *  config (e.g. an MCP client). Default 90 days. */
+    readonly patTtlSeconds?: number;
+    /**
+     * Refresh grace window in seconds. A token whose `exp` has passed is still accepted
+     * by `refresh()` as long as it's within this window AND signature + loginCount check
+     * out. This makes the access TTL a "must refresh" deadline rather than a "must
+     * re-login" one, a user who closes their laptop for the weekend still gets a
+     * silent refresh on return, while revocation (loginCount mismatch) and explicit
+     * logout still force a re-login. Default 30 days (60 * 60 * 24 * 30).
+     */
+    readonly refreshGraceSeconds?: number;
+    /** Failed attempts before a lockout kicks in. Default 3. */
+    readonly maxFailedAttempts?: number;
+    /** Lockout duration once the threshold trips. Default 60s. */
+    readonly lockoutSeconds?: number;
+    /** Injected for tests; defaults to `Date.now()`. */
+    readonly now?: () => number;
+    /** Injected for tests; defaults to `crypto.randomUUID()`. */
+    readonly newId?: () => string;
+}
+declare function createLocalJwtAuth(config: LocalJwtConfig): {
+    readonly identity: IdentityProvider;
+    readonly endpoints: AuthEndpoints;
+    readonly userAdmin: UserAdminEndpoints;
+};
+
+export { FileUserStore, InMemoryUserStore, type JwtPayload, type JwtVerifyError, type JwtVerifyResult, type LocalJwtConfig, type UserRecord, type UserStore, WeakPasswordError, createLocalJwtAuth, hashPassword, signJwt, verifyJwt, verifyPassword };