@astrale-os/sdk 0.4.13 → 0.4.15

package/src/linter/project.ts

@@ -23,12 +23,23 @@ export type DomainProject = {
   root: string
   files: readonly SourceFile[]
   filesByPath: ReadonlyMap<string, SourceFile>
+  packageScopes: readonly PackageScope[]
+}
+
+type PackageScope = {
+  directory: string
+  imports: ReadonlyMap<string, string>
+}
+
+type PackageJson = {
+  imports?: Record<string, unknown>
 }
 
 export async function discoverProject(root: string): Promise<DomainProject> {
   const projectRoot = await realpath(resolve(root))
   const paths: string[] = []
-  await collectSourcePaths(projectRoot, paths)
+  const manifests: string[] = []
+  await collectProjectPaths(projectRoot, paths, manifests)
   paths.sort()
 
   const files = await Promise.all(
@@ -41,26 +52,55 @@ export async function discoverProject(root: string): Promise<DomainProject> {
     root: projectRoot,
     files,
     filesByPath: new Map(files.map((file) => [file.path, file])),
+    packageScopes: await loadPackageScopes(manifests),
   }
 }
 
-async function collectSourcePaths(directory: string, result: string[]): Promise<void> {
+async function collectProjectPaths(
+  directory: string,
+  sources: string[],
+  manifests: string[],
+): Promise<void> {
   const entries = await readdir(directory, { withFileTypes: true })
   await Promise.all(
     entries.map(async (entry) => {
       if (entry.isSymbolicLink()) return
       const path = join(directory, entry.name)
       if (entry.isDirectory()) {
-        if (!ignoredDirectories.has(entry.name)) await collectSourcePaths(path, result)
+        if (!ignoredDirectories.has(entry.name)) {
+          await collectProjectPaths(path, sources, manifests)
+        }
         return
       }
+      if (entry.isFile() && entry.name === 'package.json') manifests.push(path)
       if (!entry.isFile() || !sourceExtensions.has(extname(entry.name))) return
       if (entry.name.endsWith('.d.ts') || entry.name.includes('.gen.')) return
-      result.push(path)
+      sources.push(path)
     }),
   )
 }
 
+async function loadPackageScopes(manifests: readonly string[]): Promise<PackageScope[]> {
+  const scopes = await Promise.all(
+    manifests.map(async (manifest): Promise<PackageScope | undefined> => {
+      let packageJson: PackageJson
+      try {
+        packageJson = JSON.parse(await readFile(manifest, 'utf8')) as PackageJson
+      } catch {
+        return undefined
+      }
+      const imports = new Map<string, string>()
+      for (const [specifier, target] of Object.entries(packageJson.imports ?? {})) {
+        if (specifier.startsWith('#') && typeof target === 'string') imports.set(specifier, target)
+      }
+      return { directory: dirname(manifest), imports }
+    }),
+  )
+  return scopes
+    .filter((scope): scope is PackageScope => scope !== undefined)
+    .sort((a, b) => b.directory.length - a.directory.length)
+}
+
 export function normalizePath(path: string): string {
   return sep === '/' ? path : path.split(sep).join('/')
 }
@@ -84,8 +124,10 @@ export function resolveProjectImport(
   importer: SourceFile,
   specifier: string,
 ): SourceFile | undefined {
-  if (!specifier.startsWith('.')) return undefined
-  const unresolved = resolve(dirname(importer.path), specifier)
+  const unresolved = specifier.startsWith('.')
+    ? resolve(dirname(importer.path), specifier)
+    : resolvePackageImport(project, importer, specifier)
+  if (!unresolved) return undefined
   for (const candidate of importCandidates(unresolved)) {
     const file = project.filesByPath.get(candidate)
     if (file) return file
@@ -93,6 +135,46 @@ export function resolveProjectImport(
   return undefined
 }
 
+function resolvePackageImport(
+  project: DomainProject,
+  importer: SourceFile,
+  specifier: string,
+): string | undefined {
+  if (!specifier.startsWith('#')) return undefined
+  const scope = project.packageScopes.find(({ directory }) => isWithin(directory, importer.path))
+  if (!scope) return undefined
+  const target = scope.imports.get(specifier) ?? matchingImportTarget(scope.imports, specifier)
+  if (!target?.startsWith('./')) return undefined
+  const path = resolve(scope.directory, target)
+  return isWithin(scope.directory, path) ? path : undefined
+}
+
+function matchingImportTarget(
+  imports: ReadonlyMap<string, string>,
+  specifier: string,
+): string | undefined {
+  let best: { specificity: number; target: string } | undefined
+  for (const [pattern, target] of imports) {
+    const star = pattern.indexOf('*')
+    if (star < 0 || star !== pattern.lastIndexOf('*')) continue
+    const prefix = pattern.slice(0, star)
+    const suffix = pattern.slice(star + 1)
+    if (!specifier.startsWith(prefix) || !specifier.endsWith(suffix)) continue
+    const matchEnd = suffix.length === 0 ? specifier.length : specifier.length - suffix.length
+    const match = specifier.slice(prefix.length, matchEnd)
+    const specificity = prefix.length + suffix.length
+    if (!best || specificity > best.specificity) {
+      best = { specificity, target: target.replace('*', match) }
+    }
+  }
+  return best?.target
+}
+
+function isWithin(directory: string, path: string): boolean {
+  const child = relative(directory, path)
+  return child === '' || (!child.startsWith('..') && !isAbsolute(child))
+}
+
 function importCandidates(path: string): string[] {
   const extension = extname(path)
   const candidates = [path]

package/src/server/auxiliary-routes.ts

@@ -70,7 +70,13 @@ export type AuxiliaryRoutesConfig<TDeps> = {
    * one per RemoteFunction. Build via `buildAuxIdentityMap(compiled, key, issuer)`
    * from `sdk/src/dispatch/identity.ts`.
    */
-  identities: AuxIdentityMap
+  identities?: AuxIdentityMap
+  /** Resolve an identity lazily. Service-hosted Functions use this to read the
+   * Function node registered during deploy and reuse the Service signing key. */
+  resolveIdentity?: (
+    kind: 'view' | 'remoteFunction',
+    slug: string,
+  ) => RemoteIdentityConfig | Promise<RemoteIdentityConfig>
   /**
    * CORS policy applied to every mounted route: per-route `app.options(...)`
    * preflight and `Access-Control-Allow-*` headers on success + error
@@ -90,6 +96,7 @@ export function mountAuxiliaryRoutes<TDeps>(config: AuxiliaryRoutesConfig<TDeps>
     remoteFunctionBindings,
     deps,
     identities,
+    resolveIdentity,
     cors,
   } = config
 
@@ -100,7 +107,7 @@ export function mountAuxiliaryRoutes<TDeps>(config: AuxiliaryRoutesConfig<TDeps>
     for (const [slug, def] of Object.entries(views)) {
       const binding = viewBindings[slug]
       if (!binding || !def.render) continue
-      const identity = requireAuxIdentity('view', slug, identities.views[slug])
+      const identity = identityResolver('view', slug, identities?.views[slug], resolveIdentity)
       mountEntry({
         app,
         binding,
@@ -112,7 +119,7 @@ export function mountAuxiliaryRoutes<TDeps>(config: AuxiliaryRoutesConfig<TDeps>
         // Views are transport-only (iframe HTML/redirect). SERVER-rendered
         // views that read the graph use `ctx.fn.kernel()`: the view's own
         // identity, with narrow grants.
-        run: async ({ c, params, auth, kernel }) => {
+        run: async ({ c, params, auth, kernel, identity }) => {
           const inboundIss = auth?.credential?.verified?.iss as string | undefined
           const kernelUrl = kernel?.default ?? inboundIss
           const ctx = {
@@ -137,7 +144,12 @@ export function mountAuxiliaryRoutes<TDeps>(config: AuxiliaryRoutesConfig<TDeps>
     for (const [slug, def] of Object.entries(remoteFunctions)) {
       const binding = remoteFunctionBindings[slug]
       if (!binding) continue
-      const identity = requireAuxIdentity('remote function', slug, identities.remoteFunctions[slug])
+      const identity = identityResolver(
+        'remoteFunction',
+        slug,
+        identities?.remoteFunctions[slug],
+        resolveIdentity,
+      )
       mountEntry({
         app,
         binding,
@@ -146,7 +158,7 @@ export function mountAuxiliaryRoutes<TDeps>(config: AuxiliaryRoutesConfig<TDeps>
         auth: def.auth,
         identity,
         corsHeaders,
-        run: async ({ c, auth, kernel }) => {
+        run: async ({ c, auth, kernel, identity }) => {
           const input = await readRemoteFunctionInput(c)
           const validation = validateParams(def.inputSchema, input.params)
           if (!validation.ok) {
@@ -227,11 +239,24 @@ function requireAuxIdentity(
   )
 }
 
+function identityResolver(
+  kind: 'view' | 'remoteFunction',
+  slug: string,
+  identity: RemoteIdentityConfig | undefined,
+  resolveIdentity: AuxiliaryRoutesConfig<unknown>['resolveIdentity'],
+): () => Promise<RemoteIdentityConfig> {
+  if (resolveIdentity) return async () => resolveIdentity(kind, slug)
+  const label = kind === 'view' ? 'view' : 'remote function'
+  const required = requireAuxIdentity(label, slug, identity)
+  return async () => required
+}
+
 type RunArgs = {
   c: Context
   params: Record<string, string>
   auth: AuthContext | null
   kernel: BoundClientSessionView<FnMap> | null
+  identity: RemoteIdentityConfig
 }
 
 type MountEntryArgs = {
@@ -241,7 +266,7 @@ type MountEntryArgs = {
   defaultMethod: 'GET' | 'POST'
   run: (args: RunArgs) => Promise<Response>
   auth?: AuthPolicy
-  identity: RemoteIdentityConfig
+  identity: () => Promise<RemoteIdentityConfig>
   corsHeaders: Record<string, string>
 }
 
@@ -296,10 +321,11 @@ function mountEntry(args: MountEntryArgs): void {
         if (value !== undefined) pathParams[name] = decodeURIComponent(value)
       }
 
+      const resolvedIdentity = await identity()
       const { auth: resolvedAuth, kernel } = await resolveInboundAuth(
         stripBearerPrefix(c.req.header('authorization') ?? ''),
         auth,
-        identity,
+        resolvedIdentity,
       )
 
       const response = await run({
@@ -307,6 +333,7 @@ function mountEntry(args: MountEntryArgs): void {
         params: { ...hostParams, ...pathParams },
         auth: resolvedAuth,
         kernel,
+        identity: resolvedIdentity,
       })
       return applyCorsToResponse(response, corsHeaders)
     } catch (err) {

package/src/server/index.ts

@@ -4,8 +4,16 @@ export type { RemoteServer, RemoteServerHandle } from './handle.js'
 export { derivePublicJwk } from './jwks.js'
 export { requireEnv } from './require-env.js'
 export { canonicalizeServingUrl } from './serving-url.js'
-export { assets, createWorkerEntry } from './worker-entry.js'
-export type { WorkerEntry, WorkerEntryConfig } from './worker-entry.js'
+export { assets, createAppWorkerEntry, createWorkerEntry } from './worker-entry.js'
+export type {
+  AppWorkerEntryConfig,
+  Fetcher,
+  WorkerApp,
+  WorkerEntry,
+  WorkerEntryConfig,
+} from './worker-entry.js'
 export { domainWorkerEntry } from './domain-entry.js'
 export type { DomainWorkerEntryConfig } from './domain-entry.js'
+export { serviceWorkerEntry } from './service-entry.js'
+export type { ServiceWorkerEntryConfig, ServiceWorkerIdentityEnv } from './service-entry.js'
 export { startNodeServer } from './start.js'

package/src/server/service-entry.ts

@@ -0,0 +1,209 @@
+import type { FunctionBinding } from '@astrale-os/kernel-api/routed'
+import type { Node } from '@astrale-os/kernel-core'
+import type { CorsConfig } from '@astrale-os/kernel-server'
+
+import { K } from '@astrale-os/kernel-core'
+import { Hono } from 'hono'
+
+import type { RemoteIdentityConfig } from '../auth/identity.js'
+import type { AnyRemoteFunctionDef } from '../define/remote-function.js'
+import type { Fetcher, WorkerEntry } from './worker-entry.js'
+
+import { makeFunctionContext } from '../auth/function-context.js'
+import { buildFunctionSchemas, DEFAULT_FUNCTIONS_FOLDER } from '../domain/extend-functions.js'
+import {
+  SERVICE_FUNCTIONS_PATH,
+  ServiceFunctionDiscoveryRequestSchema,
+  signServiceFunctionManifest,
+  toServiceFunctionManifestEntries,
+} from '../service/functions.js'
+import { mountAuxiliaryRoutes } from './auxiliary-routes.js'
+import { createAppWorkerEntry } from './worker-entry.js'
+
+export interface ServiceWorkerIdentityEnv {
+  IDENTITY_ISS?: string
+  IDENTITY_SUB?: string
+  IDENTITY_PRIVATE_KEY?: string
+  ASTRALE_KERNEL_AUDIENCE?: string
+}
+
+export interface ServiceWorkerEntryConfig<TEnv extends ServiceWorkerIdentityEnv> {
+  functions?: Record<string, AnyRemoteFunctionDef>
+  functionsFolder?: string
+  cors?: CorsConfig
+  resolveUrl?: (env: TEnv, requestOrigin: string) => string
+  selfBinding?: (env: TEnv) => Fetcher | null | undefined
+  routeSubrequest?: (url: URL, env: TEnv) => Fetcher | null | undefined
+}
+
+/** A Service worker with zero or more first-class kernel Functions.
+ *
+ * The function map is the only declaration: it drives both HTTP routes and the
+ * signed deploy-time manifest. Function identities are read lazily from the
+ * graph after Services has reconciled them, while every Function reuses the
+ * Service's one private signing key. */
+export function serviceWorkerEntry<TEnv extends ServiceWorkerIdentityEnv>(
+  config: ServiceWorkerEntryConfig<TEnv>,
+): WorkerEntry<TEnv> {
+  const functions = config.functions ?? {}
+  const functionsFolder = config.functionsFolder ?? DEFAULT_FUNCTIONS_FOLDER
+
+  return createAppWorkerEntry<TEnv>({
+    buildApp: (url, env) => {
+      const app = new Hono()
+      const serviceIdentity = identityFromEnv(env)
+      const { schemas, bindings } = buildFunctionSchemas(functions, url, functionsFolder)
+      assertLocalBindings(url, bindings)
+      const resolveFunctionIdentity = createFunctionIdentityResolver(env, serviceIdentity)
+
+      app.get('/', (c) => c.json({ ok: true, kind: 'astrale-service' }))
+      app.post(SERVICE_FUNCTIONS_PATH, async (c) => {
+        const parsed = ServiceFunctionDiscoveryRequestSchema.safeParse(
+          await c.req.json().catch(() => null),
+        )
+        if (!parsed.success) {
+          return c.json({ error: 'Invalid service function discovery request' }, 400)
+        }
+        const response = await signServiceFunctionManifest(
+          {
+            version: 1,
+            service: {
+              issuer: serviceIdentity.issuer,
+              subject: serviceIdentity.subject,
+            },
+            functions: toServiceFunctionManifestEntries(schemas),
+          },
+          parsed.data,
+          serviceIdentity,
+        )
+        return c.json(response)
+      })
+
+      mountAuxiliaryRoutes({
+        app,
+        url,
+        remoteFunctions: functions,
+        remoteFunctionBindings: bindings,
+        deps: env,
+        resolveIdentity: (kind, slug) => {
+          if (kind !== 'remoteFunction') {
+            throw new Error(`serviceWorkerEntry cannot resolve ${kind} identity ${slug}`)
+          }
+          return resolveFunctionIdentity(slug)
+        },
+        cors: config.cors ?? { origin: '*' },
+      })
+      return app
+    },
+    resolveUrl: config.resolveUrl ?? ((_env, requestOrigin) => requestOrigin),
+    selfBinding: config.selfBinding,
+    routeSubrequest: config.routeSubrequest,
+  })
+}
+
+function identityFromEnv<TEnv extends ServiceWorkerIdentityEnv>(env: TEnv): RemoteIdentityConfig {
+  return {
+    issuer: required(env, 'IDENTITY_ISS'),
+    subject: required(env, 'IDENTITY_SUB'),
+    privateKey: parsePrivateKey(required(env, 'IDENTITY_PRIVATE_KEY')),
+  }
+}
+
+function createFunctionIdentityResolver<TEnv extends ServiceWorkerIdentityEnv>(
+  env: TEnv,
+  serviceIdentity: RemoteIdentityConfig,
+): (slug: string) => Promise<RemoteIdentityConfig> {
+  const kernelUrl = required(env, 'ASTRALE_KERNEL_AUDIENCE')
+  let cachedAt = 0
+  let identities = new Map<string, { issuer: string; subject: string }>()
+  const ttlMs = 60_000
+
+  return async (slug) => {
+    if (Date.now() - cachedAt >= ttlMs || !identities.has(slug)) {
+      const kernel = await makeFunctionContext(serviceIdentity, env, {
+        ref: 'service',
+        defaultKernelUrl: kernelUrl,
+      }).kernel()
+      const service = await kernel.get(`@${serviceIdentity.subject}`)
+      if (!service) throw new Error(`Service @${serviceIdentity.subject} is not readable`)
+      const folder = await kernel.get(`${service.path.raw}/functions`)
+      const nodes = folder
+        ? await (
+            await kernel.children(folder.path, {
+              classes: [K.$.c('Function').path.class],
+              limit: 500,
+            })
+          ).all()
+        : []
+      identities = readFunctionIdentities(nodes, serviceIdentity.issuer)
+      cachedAt = Date.now()
+    }
+    const identity = identities.get(slug)
+    if (!identity) throw new Error(`Function identity function.${slug} is not registered`)
+    return hostedFunctionIdentity(identity, serviceIdentity)
+  }
+}
+
+/** Reuse only the Service's signing key. A hosted Function's inbound audience
+ * defaults to its own issuer; the Service HTTP origin is merely transport. */
+export function hostedFunctionIdentity(
+  identity: { issuer: string; subject: string },
+  serviceIdentity: RemoteIdentityConfig,
+): RemoteIdentityConfig {
+  return { ...identity, privateKey: serviceIdentity.privateKey }
+}
+
+function readFunctionIdentities(
+  nodes: readonly Node[],
+  serviceIssuer: string,
+): Map<string, { issuer: string; subject: string }> {
+  const result = new Map<string, { issuer: string; subject: string }>()
+  for (const node of nodes) {
+    const ref = node.props[K.$.i('Function').ref.key]
+    const issuer = node.props[K.Identity.iss.key]
+    const subject = node.props[K.Identity.sub.key]
+    if (
+      typeof ref !== 'string' ||
+      !ref.startsWith('function.') ||
+      typeof issuer !== 'string' ||
+      typeof subject !== 'string'
+    ) {
+      continue
+    }
+    if (issuer !== serviceIssuer) {
+      throw new Error(`Function ${ref} does not share its hosting Service issuer`)
+    }
+    result.set(ref.slice('function.'.length), { issuer, subject })
+  }
+  return result
+}
+
+function assertLocalBindings(url: string, bindings: Record<string, FunctionBinding>): void {
+  const origin = new URL(url).origin
+  for (const [slug, binding] of Object.entries(bindings)) {
+    if (!binding.remoteUrl || new URL(binding.remoteUrl).origin !== origin) {
+      throw new Error(`serviceWorkerEntry function.${slug} must be hosted by this Service origin`)
+    }
+  }
+}
+
+function required<TEnv extends ServiceWorkerIdentityEnv>(env: TEnv, key: keyof TEnv): string {
+  const value = env[key]
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new Error(`Missing service variable ${String(key)}`)
+  }
+  return value
+}
+
+function parsePrivateKey(value: string): JsonWebKey {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(value)
+  } catch (error) {
+    throw new Error('IDENTITY_PRIVATE_KEY is not valid JSON', { cause: error })
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error('IDENTITY_PRIVATE_KEY is not a JWK object')
+  }
+  return parsed as JsonWebKey
+}

package/src/server/worker-entry.ts

@@ -30,8 +30,8 @@ import { createRemoteServer } from './create.js'
 import { requireEnv } from './require-env.js'
 import { canonicalizeServingUrl } from './serving-url.js'
 
-type Fetcher = { fetch(request: Request): Response | Promise<Response> }
-type App = {
+export type Fetcher = { fetch(request: Request): Response | Promise<Response> }
+export type WorkerApp = {
   fetch(
     request: Request,
     env?: unknown,
@@ -41,7 +41,7 @@ type App = {
 
 /** A built app cached by its serving URL: `origin` for same-origin matching,
  * `app` for in-process self-dispatch. */
-type CachedApp = { origin: string; app: App }
+type CachedApp = { origin: string; app: WorkerApp }
 
 /**
  * Choose where an OUTBOUND subrequest to `u` is routed — or `null` to let the
@@ -137,6 +137,10 @@ export interface WorkerEntryConfig<TDeps> {
   rewriteRequest?: (env: TDeps, request: Request) => Request
 }
 
+export interface AppWorkerEntryConfig<TDeps> extends Omit<WorkerEntryConfig<TDeps>, 'build'> {
+  buildApp: (url: string, env: TDeps) => WorkerApp
+}
+
 export interface WorkerEntry<TDeps> {
   fetch(request: Request, env: TDeps, executionCtx?: ExecutionContext): Response | Promise<Response>
 }
@@ -201,6 +205,15 @@ export function assets<TDeps>(opts: {
 }
 
 export function createWorkerEntry<TDeps>(config: WorkerEntryConfig<TDeps>): WorkerEntry<TDeps> {
+  return createAppWorkerEntry({
+    ...config,
+    buildApp: (url, env) => createRemoteServer<TDeps>(config.build(url, env)).app,
+  })
+}
+
+export function createAppWorkerEntry<TDeps>(
+  config: AppWorkerEntryConfig<TDeps>,
+): WorkerEntry<TDeps> {
   // Cache the built app per distinct resolved URL — plural and bounded. On the
   // request-origin fallback the URL legitimately alternates for one worker
   // (direct http hits vs https-upgraded tunnel hits, workers.dev + custom
@@ -212,10 +225,10 @@ export function createWorkerEntry<TDeps>(config: WorkerEntryConfig<TDeps>): Work
   let self: Fetcher | null = null
   let routeEnv: TDeps | null = null
 
-  function getApp(url: string, env: TDeps): App {
+  function getApp(url: string, env: TDeps): WorkerApp {
     const cached = apps.get(url)
     if (cached) return cached.app
-    const { app } = createRemoteServer<TDeps>(config.build(url, env))
+    const app = config.buildApp(url, env)
     if (apps.size >= MAX_CACHED_APPS) {
       const oldest = apps.keys().next().value
       if (oldest !== undefined) apps.delete(oldest)