@astrale-os/sdk 0.1.10 → 0.3.0

package/src/auth/kernel-client.ts

@@ -20,7 +20,12 @@ import type { UnresolvedIdentityExpr } from '@astrale-os/kernel-core'
 
 import { KernelClient, SchemaRegistry, type FnMap } from '@astrale-os/kernel-client'
 import { ClientPool } from '@astrale-os/kernel-client/pool'
-import { ClientSession, type BoundClientSessionView } from '@astrale-os/kernel-client/session'
+import {
+  ClientSession,
+  allowAllDelegations,
+  delegationMintVia,
+  type BoundClientSessionView,
+} from '@astrale-os/kernel-client/session'
 
 import type { RemoteIdentityConfig } from './identity'
 
@@ -29,11 +34,6 @@ import { signCredential } from './sign'
 
 const DELEGATION_TTL_SECONDS = 3600
 
-// The kernel's whoami — returns the AUTHENTICATED principal's graph node, so
-// the resolved id satisfies the mint syscall's `self.id === auth.principal`
-// invariant by construction (same seam the shell uses to resolve self).
-const WHOAMI_PATH = '/:kernel.astrale.ai:interface.Identity:whoami'
-
 // Shared per kernel URL — the expensive, identity-agnostic state. Sessions are
 // NOT shared (each binds a subject-specific delegation mint), but the pool
 // (connections) and registry (learned schemas) are reused across them.
@@ -63,8 +63,7 @@ function getPool(url: string): ClientPool<FnMap> {
 /**
  * Build a `BoundClientSessionView` that signs outbound calls as the composed
  * identity (the caller's delegation unioned with this function's own
- * identity). Remote-bound calls auto-follow the kernel's redirect and mint a
- * worker-scoped delegation via `@<subject>::mintDelegationCredential`.
+ * identity). Remote-bound redirects mint worker-scoped delegations via AuthApi.
  */
 export async function bindKernel(
   delegation: Delegation,
@@ -117,38 +116,37 @@ async function bindSession(
     },
   )
 
-  // Self-reference in the mint closure is lazy — it only fires on a delegation
-  // cache miss while following a redirect, long after construction.
+  // The standard mint resolves the function identity through `auth.whoami()`.
   const session: ClientSession<FnMap> = new ClientSession<FnMap>({
     default: kernelUrl,
     schema: getRegistry(kernelUrl),
     pool: getPool(kernelUrl),
     delegation: {
-      // NEXT-HOP mint: each hop mints AS ITSELF. The anchor is this function's
-      // identity NODE id (resolved via whoami — `@` only accepts node ids, not
-      // paths), so `self.id === auth.principal` holds by construction. The
-      // minted delegation carries the session's authority expression (composed
-      // for delegated sessions, self-only for selfKernel): the next worker
-      // sees WHO called it while inheriting exactly that authority.
-      // `skipDelegation` keeps the whoami + mint from re-entering this
-      // closure — both target the kernel (same origin), so no delegation is
-      // needed.
-      mint: async (audience) => {
-        const selfId = await resolveSelfId(session, credential, kernelUrl, config)
-        const envelope = await session.call(
-          `@${selfId}::mintDelegationCredential`,
-          { audience, delegation: nextHopDelegation(), ttl: DELEGATION_TTL_SECONDS },
-          { credential, skipDelegation: true },
-        )
-        if (typeof envelope !== 'string') {
-          throw new Error(
-            `mintDelegationCredential returned ${typeof envelope}, expected a credential string`,
-          )
-        }
-        return { credential: envelope, ttl: DELEGATION_TTL_SECONDS }
-      },
+      mint: delegationMintVia(() => session, credential),
       ttl: DELEGATION_TTL_SECONDS,
     },
+    delegationPolicy: {
+      ...allowAllDelegations({ default: kernelUrl }),
+      delegationFor: () => nextHopDelegation(),
+    },
+  })
+  return session.as(credential)
+}
+
+/**
+ * Bind a session to a PRE-SIGNED credential — no delegation mint, no composed
+ * grant; the credential IS the authority. The seam behind
+ * `DomainIssuer.sessionFor` (a worker acting as an identity it issues). Pool +
+ * schema registry are the same per-URL caches the composed sessions use.
+ */
+export function bindCredentialSession(
+  kernelUrl: string,
+  credential: string,
+): BoundClientSessionView<FnMap> {
+  const session = new ClientSession<FnMap>({
+    default: kernelUrl,
+    schema: getRegistry(kernelUrl),
+    pool: getPool(kernelUrl),
   })
   return session.as(credential)
 }
@@ -178,33 +176,3 @@ export function makeSelfKernel(
     return bindSelfKernel(url, identity)
   }
 }
-
-// Function-identity node ids, cached per (kernel, issuer, subject). Sessions
-// are per-request, but a function's identity node is stable for the worker's
-// lifetime — one whoami per function, not one per redirect.
-const selfIds = new Map<string, string>()
-
-/**
- * Resolve THIS function's identity node id on the parent kernel via whoami,
- * authenticated with the composed credential (whose principal IS the function).
- */
-async function resolveSelfId(
-  session: ClientSession<FnMap>,
-  credential: string,
-  kernelUrl: string,
-  config: RemoteIdentityConfig,
-): Promise<string> {
-  const key = `${kernelUrl}|${config.issuer}|${config.subject}`
-  const cached = selfIds.get(key)
-  if (cached) return cached
-  const me = (await session.call(WHOAMI_PATH, {}, { credential, skipDelegation: true })) as {
-    id?: string
-  } | null
-  if (!me?.id) {
-    throw new Error(
-      `whoami returned no identity node for ${config.subject} — cannot anchor the next-hop delegation mint`,
-    )
-  }
-  selfIds.set(key, me.id)
-  return me.id
-}

package/src/cli/dotenv.ts

@@ -43,3 +43,23 @@ export function loadDotenvFile(path: string): Record<string, string> {
   }
   return parseDotenv(contents)
 }
+
+/**
+ * Read + parse a dotenv file the preset explicitly DECLARED (`secrets:`).
+ * Declared-but-absent is a wiring error (the gitignored file was never created
+ * on this machine), so it throws instead of loading `{}` — silently forwarding
+ * nothing surfaces much later as an empty credential at the provider. A file
+ * that exists but holds no keys is legitimate (a domain with no secrets yet).
+ */
+export function loadDeclaredSecrets(path: string, declaration: string): Record<string, string> {
+  let contents: string
+  try {
+    contents = readFileSync(path, 'utf-8')
+  } catch {
+    throw new Error(
+      `Secrets file '${declaration}' is declared in the preset but missing at ${path}. ` +
+        `Create it (it may be empty) or remove 'secrets:' from the preset.`,
+    )
+  }
+  return parseDotenv(contents)
+}

package/src/cli/index.ts

@@ -12,4 +12,4 @@
  */
 
 export { run, parseArgs } from './run'
-export { parseDotenv, loadDotenvFile } from './dotenv'
+export { parseDotenv, loadDotenvFile, loadDeclaredSecrets } from './dotenv'

package/src/cli/log.ts

@@ -0,0 +1,18 @@
+/** CLI output helpers + ANSI colours, shared by run.ts and publish.ts. */
+
+export const GREEN = '\x1b[32m'
+export const DIM = '\x1b[2m'
+export const BOLD = '\x1b[1m'
+export const YELLOW = '\x1b[33m'
+export const RED = '\x1b[31m'
+export const RESET = '\x1b[0m'
+
+export function info(msg: string): void {
+  process.stdout.write(`${DIM}›${RESET} ${msg}\n`)
+}
+export function warn(msg: string): void {
+  process.stderr.write(`${YELLOW}!${RESET} ${msg}\n`)
+}
+export function error(msg: string): void {
+  process.stderr.write(`${RED}✗${RESET} ${msg}\n`)
+}

package/src/cli/publish.ts

@@ -0,0 +1,341 @@
+/**
+ * All `publish` logic — the schema-publish step, the admin-catalog register, and
+ * the release orchestration tying them together. `run.ts` only parses args and
+ * dispatches here.
+ *
+ * A release has two halves that must stay in sync: the CONTRACT (the `./schema`
+ * package on npm, so other domains can `imports`/`implements`/`extends` it) and
+ * the DEPLOYMENT (the worker URL in the admin catalog). They run npm-FIRST — npm
+ * publish is irreversible, so the catalog is registered only on schema-publish
+ * success, never pointing at an unpublished contract.
+ *
+ * Why `pnpm pack` then `npm publish <tarball>` (not a plain `npm publish`): a
+ * schema package ships only `dist` and uses `publishConfig` to repoint
+ * main/exports from source `.ts` to `dist` — a field override only PNPM applies,
+ * so npm would otherwise publish an entry pointing at unshipped source.
+ */
+import { spawn } from 'node:child_process'
+import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { BOLD, DIM, error, GREEN, info, RESET, warn } from './log'
+
+type SchemaPkg = {
+  name?: string
+  version?: string
+  private?: boolean
+  files?: readonly string[]
+  peerDependencies?: Record<string, string>
+  dependencies?: Record<string, string>
+  optionalDependencies?: Record<string, string>
+  publishConfig?: { access?: string }
+}
+
+// ── release orchestration (schema THEN catalog) ──────────────────────────────
+
+/** `publish` (no deploy): publish the schema, then register the deployed URL. */
+export async function runRelease(opts: {
+  projectDir: string
+  origin: string
+  name?: string
+  publicUrl?: string
+  skipSchema: boolean
+  dryRun: boolean
+  otp?: string
+  installByDefault?: boolean
+}): Promise<number> {
+  const schemaCode = await publishSchemaBeforeCatalog(opts.projectDir, opts)
+  if (schemaCode !== 0) return schemaCode
+
+  const url = opts.publicUrl ?? `https://${opts.origin}`
+  if (opts.dryRun) {
+    info(`dry-run: would register ${opts.origin} → ${url} in the admin catalog (not registered).`)
+    return 0
+  }
+  info(`registering ${opts.origin} → ${url} in the admin catalog (no deploy)`)
+  return await registerCatalog(opts.projectDir, opts, url)
+}
+
+/** The `deploy --publish` tail: publish the schema, then register the just-deployed URL. */
+export async function runReleaseAfterDeploy(opts: {
+  projectDir: string
+  origin: string
+  deployedUrl: string
+  name?: string
+  skipSchema: boolean
+  otp?: string
+  installByDefault?: boolean
+}): Promise<number> {
+  const schemaCode = await publishSchemaBeforeCatalog(opts.projectDir, { ...opts, dryRun: false })
+  if (schemaCode !== 0) return schemaCode
+  return await registerCatalog(opts.projectDir, opts, opts.deployedUrl)
+}
+
+/**
+ * The schema half of a release. npm publish is irreversible, so it runs FIRST:
+ * returns 0 to proceed (published | skipped | no `./schema` package), non-zero to
+ * ABORT before the catalog touch — so the catalog never points at an unpublished
+ * contract.
+ */
+async function publishSchemaBeforeCatalog(
+  projectDir: string,
+  opts: { skipSchema: boolean; dryRun: boolean; otp?: string },
+): Promise<number> {
+  if (opts.skipSchema) return 0
+  if (!existsSync(join(projectDir, 'schema', 'package.json'))) {
+    info('no ./schema package — registering the catalog only.')
+    return 0
+  }
+  const code = await publishSchema({
+    projectDir,
+    schemaDir: 'schema',
+    dryRun: opts.dryRun,
+    ...(opts.otp !== undefined ? { otp: opts.otp } : {}),
+  })
+  if (code !== 0)
+    error(
+      'schema publish failed — NOT registering the catalog (a catalog entry must never point ' +
+        'at an unpublished contract). Fix the schema package and re-run, or pass --skip-schema.',
+    )
+  return code
+}
+
+/**
+ * Register a domain's public URL in the admin catalog by shelling out to the
+ * operator CLI (`astrale domain publish`). Deliberately a subprocess: all
+ * credential/admin-target resolution lives in `@astrale-os/cli`, kept out of
+ * this build tool. A missing `astrale` is reported with the exact line to run by
+ * hand. The catalog `name` is a short slug (the origin's first label by default),
+ * distinct from the FQDN origin and from any `@scope/…` npm package name.
+ */
+async function registerCatalog(
+  projectDir: string,
+  opts: { origin: string; name?: string; installByDefault?: boolean },
+  url: string,
+): Promise<number> {
+  const { description } = readPackageMeta(projectDir)
+  const name = opts.name ?? opts.origin.split('.')[0] ?? opts.origin
+  // `--public-url`, not `--url`: the operator CLI reserves `--url` for kernel targeting.
+  const cliArgs = [
+    'domain',
+    'publish',
+    '--origin',
+    opts.origin,
+    '--name',
+    name,
+    '--public-url',
+    url,
+  ]
+  if (description) cliArgs.push('--description', description)
+  if (opts.installByDefault) cliArgs.push('--install-by-default')
+
+  info(`publishing to the admin catalog → astrale ${cliArgs.join(' ')}`)
+  return await new Promise<number>((resolve) => {
+    const child = spawn('astrale', cliArgs, { stdio: 'inherit' })
+    child.on('error', (err) => {
+      if ((err as NodeJS.ErrnoException).code === 'ENOENT')
+        error(
+          `\`astrale\` CLI not found on PATH. Register it by hand:\n      astrale ${cliArgs.join(' ')}`,
+        )
+      else error(`failed to run \`astrale domain publish\`: ${err.message}`)
+      resolve(1)
+    })
+    child.on('exit', (code) => resolve(code ?? 1))
+  })
+}
+
+function readPackageMeta(projectDir: string): { name?: string; description?: string } {
+  try {
+    return JSON.parse(readFileSync(join(projectDir, 'package.json'), 'utf8')) as {
+      name?: string
+      description?: string
+    }
+  } catch {
+    return {}
+  }
+}
+
+// ── schema publish ───────────────────────────────────────────────────────────
+
+/**
+ * Build a domain's thin schema package and publish it to npm. Operates on the
+ * schema PACKAGE (its own package.json), not astrale.config.ts, so it needs no
+ * adapter — `publish --schema` runs it config-free.
+ */
+export async function publishSchema(args: {
+  projectDir: string
+  /** Schema-package dir. Default: `<projectDir>/schema`, else `<projectDir>`. */
+  schemaDir?: string
+  dryRun: boolean
+  /** 2FA one-time password forwarded to `npm publish`. */
+  otp?: string
+}): Promise<number> {
+  const dir = resolveSchemaDir(args.projectDir, args.schemaDir)
+  if (!dir) {
+    error(
+      `No schema package found (no package.json at ./schema or the current dir). A schema\n` +
+        `  package declares peerDependencies (@astrale-os/kernel-core + kernel-dsl + zod) and a\n` +
+        `  publishConfig that repoints main/exports to ./dist — see domains/workspace/schema.`,
+    )
+    return 1
+  }
+
+  const pkgPath = join(dir, 'package.json')
+  let pkg: SchemaPkg
+  try {
+    pkg = JSON.parse(readFileSync(pkgPath, 'utf8')) as SchemaPkg
+  } catch (err) {
+    error(`Could not read ${pkgPath}: ${(err as Error).message}`)
+    return 1
+  }
+
+  const problems = preflight(pkg)
+  if (problems.length > 0) {
+    error(`Schema package is not ready to publish (${pkgPath}):`)
+    for (const p of problems) process.stderr.write(`    • ${p}\n`)
+    return 1
+  }
+  const name = pkg.name as string
+  const version = pkg.version as string
+
+  // Idempotent in BOTH modes: a dry-run must skip too, since `npm publish
+  // --dry-run` still validates against the registry and errors on an existing version.
+  if (await isOnRegistry(name, version)) {
+    info(
+      `${BOLD}${name}@${version}${RESET} is already published — ` +
+        (args.dryRun ? `a real run would skip it.` : `bump the version to ship again.`),
+    )
+    return 0
+  }
+
+  const dest = mkdtempSync(join(tmpdir(), 'astrale-schema-pack-'))
+  try {
+    info(`packing ${BOLD}${name}@${version}${RESET} from ${rel(args.projectDir, dir)}`)
+    if ((await runInherit('pnpm', ['pack', '--pack-destination', dest], dir)) !== 0) {
+      error(`pnpm pack failed — see the build output above.`)
+      return 1
+    }
+    const tarball = readdirSync(dest)
+      .filter((f) => f.endsWith('.tgz'))
+      .map((f) => join(dest, f))[0]
+    if (!tarball) {
+      error(`pnpm pack produced no .tgz in ${dest}.`)
+      return 1
+    }
+
+    // `--access` mirrors the manifest's baked publishConfig.access; npm's 2FA
+    // prompt passes through `stdio: 'inherit'` (or `--otp` for non-interactive).
+    const access = pkg.publishConfig?.access ?? 'public'
+    const publishArgs = [
+      'publish',
+      tarball,
+      '--access',
+      access,
+      ...(args.dryRun ? ['--dry-run'] : []),
+      ...(args.otp ? ['--otp', args.otp] : []),
+    ]
+    info(
+      args.dryRun
+        ? `dry-run: ${DIM}npm ${publishArgs.join(' ')}${RESET}`
+        : `publishing ${DIM}(a browser / OTP prompt may appear for 2FA)${RESET}`,
+    )
+    const code = await runInherit('npm', publishArgs)
+    if (code !== 0) {
+      error(
+        `npm publish exited ${code}. An auth error (E401/E404) usually means the session ` +
+          `expired — \`npm login\` and retry.`,
+      )
+      return code
+    }
+    if (args.dryRun) info(`dry-run complete — nothing was published.`)
+    else printPublished(name, version)
+    return 0
+  } finally {
+    try {
+      rmSync(dest, { recursive: true, force: true })
+    } catch {
+      warn(`(non-fatal) could not clean the temp pack dir ${dest}`)
+    }
+  }
+}
+
+/** Locate the schema package: an explicit path, else `<projectDir>/schema`, else `<projectDir>`. */
+function resolveSchemaDir(projectDir: string, explicit?: string): string | undefined {
+  const candidates = explicit
+    ? [join(projectDir, explicit)]
+    : [join(projectDir, 'schema'), projectDir]
+  return candidates.find((c) => existsSync(join(c, 'package.json')))
+}
+
+/** Static guards against the classic schema-publish footguns, before any network call. */
+function preflight(pkg: SchemaPkg): string[] {
+  const problems: string[] = []
+  if (!pkg.name) problems.push('package.json has no "name".')
+  if (!pkg.version) problems.push('package.json has no "version".')
+  else if (!/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(pkg.version))
+    problems.push(`"version" ("${pkg.version}") must be an exact semver, not a range.`)
+  if (pkg.private) problems.push('"private": true — remove it to publish.')
+  // Peers, not deps: bundling kernel-core/dsl/zod gives the consumer a 2nd copy
+  // and breaks the def `__brand` identity at compile time.
+  if (!pkg.peerDependencies || Object.keys(pkg.peerDependencies).length === 0)
+    problems.push(
+      'no "peerDependencies" — peer-depend on @astrale-os/kernel-core (+ kernel-dsl, zod).',
+    )
+  if (!pkg.files?.includes('dist'))
+    problems.push('"files" must include "dist" (ship only the built output).')
+  if (!pkg.publishConfig)
+    problems.push('no "publishConfig" — main/types/exports won\'t repoint to ./dist at pack time.')
+  for (const field of ['dependencies', 'peerDependencies', 'optionalDependencies'] as const) {
+    for (const [dep, spec] of Object.entries(pkg[field] ?? {})) {
+      if (/^(link:|file:|workspace:)/.test(spec))
+        problems.push(
+          `${field}["${dep}"] is "${spec}" — npm can't publish that; use a semver range.`,
+        )
+    }
+  }
+  return problems
+}
+
+/** True if `<name>@<version>` already exists on the registry. */
+async function isOnRegistry(name: string, version: string): Promise<boolean> {
+  return await new Promise<boolean>((resolve) => {
+    let out = ''
+    const child = spawn('npm', ['view', `${name}@${version}`, 'version'], {
+      stdio: ['ignore', 'pipe', 'ignore'],
+    })
+    child.stdout?.on('data', (d) => (out += String(d)))
+    child.on('error', () => resolve(false)) // npm missing / not-found / offline → let publish surface it
+    child.on('exit', () => resolve(out.trim().length > 0))
+  })
+}
+
+async function runInherit(cmd: string, cmdArgs: readonly string[], cwd?: string): Promise<number> {
+  return await new Promise<number>((resolve) => {
+    const child = spawn(cmd, cmdArgs as string[], { stdio: 'inherit', ...(cwd ? { cwd } : {}) })
+    child.on('error', (err) => {
+      const c = (err as NodeJS.ErrnoException).code
+      error(
+        c === 'ENOENT'
+          ? `\`${cmd}\` not found on PATH.`
+          : `failed to run \`${cmd}\`: ${err.message}`,
+      )
+      resolve(1)
+    })
+    child.on('exit', (code) => resolve(code ?? 1))
+  })
+}
+
+function printPublished(name: string, version: string): void {
+  process.stdout.write(
+    `\n${GREEN}✓${RESET} published ${BOLD}${name}@${version}${RESET}\n` +
+      `  ${DIM}consume it:${RESET} ${BOLD}import { schema as S } from '${name}'${RESET}` +
+      `${DIM} → imports: [S], implements: [S.interfaces.X]${RESET}\n` +
+      `  ${DIM}and add ${BOLD}requires: ['<this-origin>']${RESET}${DIM} on the consumer ` +
+      `(producer installs first).${RESET}\n\n`,
+  )
+}
+
+function rel(from: string, to: string): string {
+  return to.startsWith(from) ? `.${to.slice(from.length) || '/'}` : to
+}