/**
 * `RemoteServerConfig` — input shape for `createRemoteServer`.
 *
 * Identity is per-function: `iss` = the worker's serving URL (`config.url`),
 * `sub` = the function path, signed on each dispatch. No single `subject`.
 */

import type { CorsConfig, WsAdapter } from '@astrale-os/kernel-server'
import type { Context } from 'hono'
import type { Hono } from 'hono'

import type { RemoteDomain } from '../domain/define.js'

export type RemoteServerConfig<TDeps> = {
  /** Domain produced by `defineRemoteDomain(...)`. */
  domain: RemoteDomain
  /** Dependency container passed to every handler as `ctx.deps`. */
  deps: TDeps
  /**
   * Server URL — the serving location AND the worker's JWT issuer identity
   * (`iss`), decoupled from the addressing `origin` slug.
   *
   * The server's public key is published at `<url>/.well-known/jwks.json`
   * so downstream verifiers can validate credentials signed by this server.
   */
  url: string
  /** Private key used to sign outbound credentials. Public form is exposed via JWKS. */
  privateKey: JsonWebKey
  /** Allowed transports. `'http'` is mandatory. `'ws'` is opt-in. Defaults to `['http']`. */
  transports?: readonly ('http' | 'ws')[]
  /**
   * Runtime-specific WS adapter (from `hono/bun`, `@hono/node-ws`, `hono/deno`).
   * Required when `transports` includes `'ws'`.
   */
  ws?: WsAdapter
  /** CORS configuration. Defaults to `{ origin: '*' }`. */
  cors?: CorsConfig
  /** Optional health endpoint path (defaults to `/health`; `false` disables). */
  health?: string | false
  /** Pre-existing Hono app to attach to (for nesting the SDK under a parent router). */
  app?: Hono
  /**
   * Provenance stamped onto the auto-mounted `/meta` endpoint. Typically
   * injected at build time by the bundler so downstream tooling can detect
   * version drift between deployed server and expected schema.
   */
  meta?: {
    sdkCommit?: string
    schemaHash?: string
    domainName?: string
  }
  /**
   * Typed colon-path to a callable the installing kernel calls ONCE as the
   * system identity, immediately after the domain installs. Use it to seed
   * nodes and self-grant. Must be a semantic domain path under this domain's
   * own origin (`/:origin:class.X:seed` / `/:origin:interface.Ops:seed`) — the
   * kernel's origin guard refuses absolute tree paths, which cannot prove
   * their origin from the string alone. Returned verbatim in the install
   * bundle (a routing hint — the signed `graph_hash` already constrains what
   * the callable can be).
   *
   * Example: `/:crm.acme.dev:class.Note:seed`
   */
  postInstall?: string
  /**
   * Cross-domain dependencies by origin. Returned in the install bundle; the
   * kernel verifies each origin is already present on the instance before
   * installing, and refuses with a clear error if one is missing.
   */
  requires?: readonly string[]
  /**
   * Optional private install hook. Throw to deny the install request.
   * The public URL install contract still receives no caller kernel
   * credential; private installs use the bearer token only.
   */
  install?: {
    authorize?: (args: {
      c: Context
      token?: string
      kernelIssuer: string
      nonce: string
      deps: TDeps
    }) => void | Promise<void>
  }
}