@astrale-os/sdk 0.1.1 → 0.1.3

package/dist/server/handle.js

@@ -0,0 +1,9 @@
+/**
+ * `RemoteServer` and `RemoteServerHandle` — output shapes for the SDK server.
+ *
+ * `RemoteServer` is what `createRemoteServer` returns: the assembled Hono
+ * app plus a Node convenience helper. `RemoteServerHandle` is what `start()`
+ * resolves to: the bound port and a `close()` function for graceful shutdown.
+ */
+export {};
+//# sourceMappingURL=handle.js.map

package/dist/server/handle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handle.js","sourceRoot":"","sources":["../../src/server/handle.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/server/index.d.ts

@@ -0,0 +1,11 @@
+export { createRemoteServer } from './create';
+export type { RemoteServerConfig } from './config';
+export type { RemoteServer, RemoteServerHandle } from './handle';
+export { derivePublicJwk } from './jwks';
+export { requireEnv } from './require-env';
+export { canonicalizeServingUrl } from './serving-url';
+export { createWorkerEntry } from './worker-entry';
+export type { WorkerEntry, WorkerEntryConfig } from './worker-entry';
+export { workerMeta } from './worker-meta';
+export { startNodeServer } from './start';
+//# sourceMappingURL=index.d.ts.map

package/dist/server/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAA;AAC7C,YAAY,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAA;AAClD,YAAY,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAA;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAA;AACxC,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAC1C,OAAO,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAA;AACtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;AAClD,YAAY,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;AACpE,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA"}

package/dist/server/index.js

@@ -0,0 +1,8 @@
+export { createRemoteServer } from './create';
+export { derivePublicJwk } from './jwks';
+export { requireEnv } from './require-env';
+export { canonicalizeServingUrl } from './serving-url';
+export { createWorkerEntry } from './worker-entry';
+export { workerMeta } from './worker-meta';
+export { startNodeServer } from './start';
+//# sourceMappingURL=index.js.map

package/dist/server/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAA;AAG7C,OAAO,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAA;AACxC,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAC1C,OAAO,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAA;AACtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;AAElD,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA"}

package/dist/server/jwks.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Derive a public JWK from a private one.
+ *
+ * Strips the private components for both EC keys (drops `d`) and RSA keys
+ * (drops `d`, `p`, `q`, `dp`, `dq`, `qi`, and `oth` — the additional-primes
+ * array on multi-prime RSA keys). The result is safe to publish at
+ * `<url>/.well-known/jwks.json` so downstream verifiers can validate
+ * signatures the server produced.
+ */
+export declare function derivePublicJwk(privateKey: JsonWebKey): Record<string, unknown>;
+//# sourceMappingURL=jwks.d.ts.map

package/dist/server/jwks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwks.d.ts","sourceRoot":"","sources":["../../src/server/jwks.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,wBAAgB,eAAe,CAAC,UAAU,EAAE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAO/E"}

package/dist/server/jwks.js

@@ -0,0 +1,15 @@
+/**
+ * Derive a public JWK from a private one.
+ *
+ * Strips the private components for both EC keys (drops `d`) and RSA keys
+ * (drops `d`, `p`, `q`, `dp`, `dq`, `qi`, and `oth` — the additional-primes
+ * array on multi-prime RSA keys). The result is safe to publish at
+ * `<url>/.well-known/jwks.json` so downstream verifiers can validate
+ * signatures the server produced.
+ */
+export function derivePublicJwk(privateKey) {
+    // oxlint-disable-next-line no-unused-vars
+    const { d, p, q, dp, dq, qi, oth, ...publicJwk } = privateKey;
+    return publicJwk;
+}
+//# sourceMappingURL=jwks.js.map

package/dist/server/jwks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwks.js","sourceRoot":"","sources":["../../src/server/jwks.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,UAAU,eAAe,CAAC,UAAsB;IACpD,0CAA0C;IAC1C,MAAM,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,GAAG,SAAS,EAAE,GAAG,UAGlD,CAAA;IACD,OAAO,SAAS,CAAA;AAClB,CAAC"}

package/dist/server/require-env.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Read a string-typed env var (process.env on Node, the Worker `env` binding
+ * on Cloudflare) and throw a clear error if it is missing or empty.
+ *
+ * Use this for **identity-bearing** values (issuer, baseDomain, audience,
+ * worker URL) where a guessed default silently mints wrong JWTs or bakes
+ * wrong refs into persisted artifacts. The conventional `?? 'literal'`
+ * fallback is the anti-pattern this exists to replace.
+ *
+ * In local dev these live in each domain worker's `worker/.dev.vars` (read
+ * natively by `wrangler dev`), so this throw never fires in a properly-prepared
+ * dev environment — only when wiring is genuinely missing.
+ */
+export declare function requireEnv(env: unknown, name: string, hint?: string): string;
+//# sourceMappingURL=require-env.d.ts.map

package/dist/server/require-env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"require-env.d.ts","sourceRoot":"","sources":["../../src/server/require-env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAK5E"}

package/dist/server/require-env.js

@@ -0,0 +1,21 @@
+/**
+ * Read a string-typed env var (process.env on Node, the Worker `env` binding
+ * on Cloudflare) and throw a clear error if it is missing or empty.
+ *
+ * Use this for **identity-bearing** values (issuer, baseDomain, audience,
+ * worker URL) where a guessed default silently mints wrong JWTs or bakes
+ * wrong refs into persisted artifacts. The conventional `?? 'literal'`
+ * fallback is the anti-pattern this exists to replace.
+ *
+ * In local dev these live in each domain worker's `worker/.dev.vars` (read
+ * natively by `wrangler dev`), so this throw never fires in a properly-prepared
+ * dev environment — only when wiring is genuinely missing.
+ */
+export function requireEnv(env, name, hint) {
+    const v = env?.[name];
+    if (typeof v === 'string' && v.length > 0)
+        return v;
+    const help = hint ? ` (${hint})` : '';
+    throw new Error(`Missing required env var: ${name}${help}`);
+}
+//# sourceMappingURL=require-env.js.map

package/dist/server/require-env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"require-env.js","sourceRoot":"","sources":["../../src/server/require-env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,UAAU,CAAC,GAAY,EAAE,IAAY,EAAE,IAAa;IAClE,MAAM,CAAC,GAAI,GAAkD,EAAE,CAAC,IAAI,CAAC,CAAA;IACrE,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,CAAC,CAAA;IACnD,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,CAAA;IACrC,MAAM,IAAI,KAAK,CAAC,6BAA6B,IAAI,GAAG,IAAI,EAAE,CAAC,CAAA;AAC7D,CAAC"}

package/dist/server/serving-url.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Canonicalize a worker's serving URL into its `iss` identity.
+ *
+ * Returns the full URL with trailing slash(es) stripped — the base path is
+ * preserved (an issuer may carry a non-empty path, like `…/kernel/host`). This
+ * is the single canonical form used for outbound signing, the JWKS issuer,
+ * `/meta`, the install credential, and any `Identity.iss` a domain seeds, so the
+ * value a worker SIGNS always matches the value the kernel LOOKS UP (the kernel
+ * canonicalizes the verified `iss` the same way and does an exact-match lookup).
+ *
+ * Throws if `url` is not a parseable absolute URL.
+ */
+export declare function canonicalizeServingUrl(url: string): string;
+//# sourceMappingURL=serving-url.d.ts.map

package/dist/server/serving-url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serving-url.d.ts","sourceRoot":"","sources":["../../src/server/serving-url.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAOH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAS1D"}

package/dist/server/serving-url.js

@@ -0,0 +1,28 @@
+/**
+ * Canonicalize a worker's serving URL into its `iss` identity.
+ *
+ * Returns the full URL with trailing slash(es) stripped — the base path is
+ * preserved (an issuer may carry a non-empty path, like `…/kernel/host`). This
+ * is the single canonical form used for outbound signing, the JWKS issuer,
+ * `/meta`, the install credential, and any `Identity.iss` a domain seeds, so the
+ * value a worker SIGNS always matches the value the kernel LOOKS UP (the kernel
+ * canonicalizes the verified `iss` the same way and does an exact-match lookup).
+ *
+ * Throws if `url` is not a parseable absolute URL.
+ */
+// INVARIANT (cross-repo): issuer PRODUCERS must strip trailing path slashes
+// BEFORE a value becomes an iss. kernel-core's `normalizeIssuerId` only strips
+// a lone trailing slash on an EMPTY path, so `https://x/base/` and
+// `https://x/base` are distinct issuer identities to the kernel — this
+// function and the kernel's `installSourceBase` both pre-strip with the same
+// rule so the two sides can never mint diverging identities for one worker.
+export function canonicalizeServingUrl(url) {
+    try {
+        return new URL(url).href.replace(/\/+$/, '');
+    }
+    catch {
+        throw new Error(`canonicalizeServingUrl: expected a full URL (got "${url}") — ` +
+            'it is the worker serving URL and its JWT issuer identity.');
+    }
+}
+//# sourceMappingURL=serving-url.js.map

package/dist/server/serving-url.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serving-url.js","sourceRoot":"","sources":["../../src/server/serving-url.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,4EAA4E;AAC5E,+EAA+E;AAC/E,mEAAmE;AACnE,uEAAuE;AACvE,6EAA6E;AAC7E,4EAA4E;AAC5E,MAAM,UAAU,sBAAsB,CAAC,GAAW;IAChD,IAAI,CAAC;QACH,OAAO,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAA;IAC9C,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CACb,qDAAqD,GAAG,OAAO;YAC7D,2DAA2D,CAC9D,CAAA;IACH,CAAC;AACH,CAAC"}

package/dist/server/start.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Node HTTP convenience starter.
+ *
+ * Dynamically imports `@hono/node-server` so the SDK stays runtime-agnostic
+ * — only Node consumers actually pull in the dep. For Bun / Deno /
+ * Cloudflare, consumers go through `server.app.fetch` directly.
+ */
+import type { Hono } from 'hono';
+import type { RemoteServerHandle } from './handle';
+export declare function startNodeServer(app: Hono, port?: number): Promise<RemoteServerHandle>;
+//# sourceMappingURL=start.d.ts.map

package/dist/server/start.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"start.d.ts","sourceRoot":"","sources":["../../src/server/start.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAEhC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAA;AAElD,wBAAsB,eAAe,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,SAAO,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA4BzF"}

package/dist/server/start.js

@@ -0,0 +1,34 @@
+/**
+ * Node HTTP convenience starter.
+ *
+ * Dynamically imports `@hono/node-server` so the SDK stays runtime-agnostic
+ * — only Node consumers actually pull in the dep. For Bun / Deno /
+ * Cloudflare, consumers go through `server.app.fetch` directly.
+ */
+export async function startNodeServer(app, port = 3000) {
+    // Opaque specifier: the `./server` barrel re-exports this module, so worker
+    // bundles (wrangler/esbuild) traverse it even though they never call it. A
+    // literal import() would make them resolve the optional peer and fail.
+    const nodeServerModule = '@hono/node-server';
+    const { serve } = (await import(nodeServerModule));
+    // oxlint-disable-next-line no-explicit-any
+    const server = serve({ fetch: app.fetch, port });
+    await new Promise((resolve, reject) => {
+        if (server.listening)
+            return resolve();
+        server.once('listening', () => resolve());
+        // Without this, a bind failure (e.g. EADDRINUSE on a busy port) emits
+        // `'error'` and never `'listening'`, leaving the Promise — and startup —
+        // hung forever with no diagnostic.
+        server.once('error', (err) => reject(err));
+    });
+    const address = server.address();
+    const actualPort = address?.port ?? port;
+    return {
+        port: actualPort,
+        close: () => new Promise((resolve, reject) => {
+            server.close((err) => (err ? reject(err) : resolve()));
+        }),
+    };
+}
+//# sourceMappingURL=start.js.map

package/dist/server/start.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"start.js","sourceRoot":"","sources":["../../src/server/start.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,GAAS,EAAE,IAAI,GAAG,IAAI;IAC1D,4EAA4E;IAC5E,2EAA2E;IAC3E,uEAAuE;IACvE,MAAM,gBAAgB,GAAG,mBAAmB,CAAA;IAC5C,MAAM,EAAE,KAAK,EAAE,GAAG,CAAC,MAAM,MAAM,CAAC,gBAAgB,CAAC,CAAuC,CAAA;IACxF,2CAA2C;IAC3C,MAAM,MAAM,GAAG,KAAK,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,CAAQ,CAAA;IAEvD,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAC1C,IAAI,MAAM,CAAC,SAAS;YAAE,OAAO,OAAO,EAAE,CAAA;QACtC,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,CAAA;QACzC,sEAAsE;QACtE,yEAAyE;QACzE,mCAAmC;QACnC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,GAAU,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAA;IACnD,CAAC,CAAC,CAAA;IAEF,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,EAA8C,CAAA;IAC5E,MAAM,UAAU,GAAG,OAAO,EAAE,IAAI,IAAI,IAAI,CAAA;IAExC,OAAO;QACL,IAAI,EAAE,UAAU;QAChB,KAAK,EAAE,GAAG,EAAE,CACV,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACpC,MAAM,CAAC,KAAK,CAAC,CAAC,GAAiB,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAA;QACtE,CAAC,CAAC;KACL,CAAA;AACH,CAAC"}

package/dist/server/worker-entry.d.ts

@@ -0,0 +1,60 @@
+/**
+ * `createWorkerEntry` — the shared worker `fetch` plumbing every Astrale domain
+ * worker (and the cloudflare adapter's codegen) needs, so it lives in ONE place
+ * instead of being copy-pasted per worker:
+ *
+ *   • resolve the serving URL (== `iss`), canonicalize it (so the value matches
+ *     what `createRemoteServer` signs with and the kernel pins), and cache the
+ *     built app per distinct URL;
+ *   • optional self-binding routing: when a `SELF` service binding is provided,
+ *     route same-host subrequests (e.g. `ctx.callRemote` back into this domain)
+ *     through it — Cloudflare forbids a Worker fetching its own hostname. This is
+ *     the ONLY reason a `globalThis.fetch` override is installed, and only when a
+ *     `selfBinding` is configured;
+ *   • optional SPA hook (e.g. `/ui/*` served from an `ASSETS` binding).
+ *
+ * The worker's OWN JWKS (`<url>/.well-known/jwks.json`) is served as a normal
+ * route by `createRemoteServer`; the verifier resolves a self-issued credential
+ * from the in-memory key (see `auth/verify.ts`), so no self-fetch shim is needed.
+ *
+ * The worker file is then just schema + methods + a `build(url, env)` callback.
+ */
+import type { RemoteServerConfig } from './config';
+type Fetcher = {
+    fetch(request: Request): Response | Promise<Response>;
+};
+export interface WorkerEntryConfig<TDeps> {
+    /**
+     * Build the `createRemoteServer` config for the resolved serving `url`. Called
+     * once per distinct URL (the resulting app is cached), with the same `env` the
+     * request carries — so it can read additional bindings (e.g. a base domain).
+     */
+    build: (url: string, env: TDeps) => RemoteServerConfig<TDeps>;
+    /**
+     * Resolve the raw serving URL from `env` (+ the per-request origin, for workers
+     * that fall back to the request host). Defaults to the `WORKER_URL` env var.
+     * The result is always canonicalized before use.
+     */
+    resolveUrl?: (env: TDeps, requestOrigin: string) => string;
+    /** Optional: the `SELF` service binding used to route same-host subrequests. */
+    selfBinding?: (env: TDeps) => Fetcher | null | undefined;
+    /**
+     * Optional: handle a request before it reaches the kernel app — e.g. serve a
+     * SPA under `/ui/*` or a same-origin `/api/*` endpoint the view calls. Return
+     * a `Response` to short-circuit, or `undefined` to fall through to the domain
+     * dispatch.
+     */
+    before?: (env: TDeps, url: URL, request: Request) => Response | undefined | Promise<Response | undefined>;
+    /**
+     * Optional: transform the request on the fall-through path, just before it
+     * reaches the kernel app (e.g. rewrite the hostname for wildcard-subdomain
+     * routing). Not applied when `before` short-circuits.
+     */
+    rewriteRequest?: (env: TDeps, request: Request) => Request;
+}
+export interface WorkerEntry<TDeps> {
+    fetch(request: Request, env: TDeps): Response | Promise<Response>;
+}
+export declare function createWorkerEntry<TDeps>(config: WorkerEntryConfig<TDeps>): WorkerEntry<TDeps>;
+export {};
+//# sourceMappingURL=worker-entry.d.ts.map

package/dist/server/worker-entry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-entry.d.ts","sourceRoot":"","sources":["../../src/server/worker-entry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAA;AAMlD,KAAK,OAAO,GAAG;IAAE,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;CAAE,CAAA;AAGxE,MAAM,WAAW,iBAAiB,CAAC,KAAK;IACtC;;;;OAIG;IACH,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,KAAK,kBAAkB,CAAC,KAAK,CAAC,CAAA;IAC7D;;;;OAIG;IACH,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,KAAK,MAAM,CAAA;IAC1D,gFAAgF;IAChF,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,OAAO,GAAG,IAAI,GAAG,SAAS,CAAA;IACxD;;;;;OAKG;IACH,MAAM,CAAC,EAAE,CACP,GAAG,EAAE,KAAK,EACV,GAAG,EAAE,GAAG,EACR,OAAO,EAAE,OAAO,KACb,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAAA;IACzD;;;;OAIG;IACH,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,KAAK,OAAO,CAAA;CAC3D;AAED,MAAM,WAAW,WAAW,CAAC,KAAK;IAChC,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,KAAK,GAAG,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;CAClE;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,iBAAiB,CAAC,KAAK,CAAC,GAAG,WAAW,CAAC,KAAK,CAAC,CAoD7F"}

package/dist/server/worker-entry.js

@@ -0,0 +1,79 @@
+/**
+ * `createWorkerEntry` — the shared worker `fetch` plumbing every Astrale domain
+ * worker (and the cloudflare adapter's codegen) needs, so it lives in ONE place
+ * instead of being copy-pasted per worker:
+ *
+ *   • resolve the serving URL (== `iss`), canonicalize it (so the value matches
+ *     what `createRemoteServer` signs with and the kernel pins), and cache the
+ *     built app per distinct URL;
+ *   • optional self-binding routing: when a `SELF` service binding is provided,
+ *     route same-host subrequests (e.g. `ctx.callRemote` back into this domain)
+ *     through it — Cloudflare forbids a Worker fetching its own hostname. This is
+ *     the ONLY reason a `globalThis.fetch` override is installed, and only when a
+ *     `selfBinding` is configured;
+ *   • optional SPA hook (e.g. `/ui/*` served from an `ASSETS` binding).
+ *
+ * The worker's OWN JWKS (`<url>/.well-known/jwks.json`) is served as a normal
+ * route by `createRemoteServer`; the verifier resolves a self-issued credential
+ * from the in-memory key (see `auth/verify.ts`), so no self-fetch shim is needed.
+ *
+ * The worker file is then just schema + methods + a `build(url, env)` callback.
+ */
+import { createRemoteServer } from './create';
+import { requireEnv } from './require-env';
+import { canonicalizeServingUrl } from './serving-url';
+export function createWorkerEntry(config) {
+    let cache = null;
+    let self = null;
+    function getApp(url, env) {
+        if (cache && cache.url === url)
+            return cache.app;
+        const { app } = createRemoteServer(config.build(url, env));
+        cache = { url, origin: new URL(url).origin, app };
+        return app;
+    }
+    // A Worker can't fetch its own hostname. When a SELF service binding is
+    // configured, route same-host subrequests (e.g. `ctx.callRemote` back into
+    // this domain) through it. This is the only reason to override
+    // `globalThis.fetch` — workers without a `selfBinding` get no global mutation.
+    // (A self-issued credential's JWKS is resolved in-memory by the verifier, not
+    // fetched — see `auth/verify.ts` — so no self-JWKS interception is needed.)
+    if (config.selfBinding) {
+        const originalFetch = globalThis.fetch;
+        globalThis.fetch = (async (input, init) => {
+            if (cache && self) {
+                const href = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
+                try {
+                    if (new URL(href).origin === cache.origin)
+                        return self.fetch(new Request(input, init));
+                }
+                catch {
+                    // non-absolute URL — fall through to the original fetch
+                }
+            }
+            return originalFetch(input, init);
+        });
+    }
+    return {
+        async fetch(request, env) {
+            if (config.selfBinding)
+                self ??= config.selfBinding(env) ?? null;
+            // Only parse the request URL when a hook actually needs it.
+            const requestUrl = config.before || config.resolveUrl ? new URL(request.url) : null;
+            if (config.before && requestUrl) {
+                // Await so an async `before` that resolves to `undefined` falls through
+                // (a returned Promise<undefined> would otherwise be sent as the response).
+                const handled = await config.before(env, requestUrl, request);
+                if (handled !== undefined)
+                    return handled;
+            }
+            const raw = config.resolveUrl
+                ? config.resolveUrl(env, requestUrl.origin)
+                : requireEnv(env, 'WORKER_URL', "the worker's public serving URL (its iss identity)");
+            const url = canonicalizeServingUrl(raw);
+            const dispatched = config.rewriteRequest ? config.rewriteRequest(env, request) : request;
+            return getApp(url, env).fetch(dispatched);
+        },
+    };
+}
+//# sourceMappingURL=worker-entry.js.map

package/dist/server/worker-entry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-entry.js","sourceRoot":"","sources":["../../src/server/worker-entry.ts"],"names":[],"mappings":"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"}

package/dist/server/worker-meta.d.ts

@@ -0,0 +1,6 @@
+export declare function workerMeta(domainName: string): {
+    sdkCommit?: string;
+    schemaHash?: string;
+    domainName: string;
+};
+//# sourceMappingURL=worker-meta.d.ts.map

package/dist/server/worker-meta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-meta.d.ts","sourceRoot":"","sources":["../../src/server/worker-meta.ts"],"names":[],"mappings":"AAYA,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG;IAC9C,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,UAAU,EAAE,MAAM,CAAA;CACnB,CAQA"}

package/dist/server/worker-meta.js

@@ -0,0 +1,10 @@
+export function workerMeta(domainName) {
+    const sdkCommit = typeof SDK_COMMIT === 'string' ? SDK_COMMIT : undefined;
+    const schemaHash = typeof SCHEMA_HASH === 'string' ? SCHEMA_HASH : undefined;
+    return {
+        ...(sdkCommit ? { sdkCommit } : {}),
+        ...(schemaHash ? { schemaHash } : {}),
+        domainName,
+    };
+}
+//# sourceMappingURL=worker-meta.js.map

package/dist/server/worker-meta.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-meta.js","sourceRoot":"","sources":["../../src/server/worker-meta.ts"],"names":[],"mappings":"AAYA,MAAM,UAAU,UAAU,CAAC,UAAkB;IAK3C,MAAM,SAAS,GAAG,OAAO,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAAA;IACzE,MAAM,UAAU,GAAG,OAAO,WAAW,KAAK,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS,CAAA;IAC5E,OAAO;QACL,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACrC,UAAU;KACX,CAAA;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/sdk",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Astrale Remote Domain SDK - Define and deploy domains as standalone Hono servers",
   "keywords": [
     "astrale",
@@ -40,10 +40,10 @@
     "registry": "https://npm.pkg.github.com"
   },
   "dependencies": {
-    "@astrale-os/kernel-api": ">=0.4.0 <1.0.0",
-    "@astrale-os/kernel-client": ">=0.1.0 <1.0.0",
-    "@astrale-os/kernel-core": ">=0.3.0 <1.0.0",
-    "@astrale-os/kernel-dsl": ">=0.1.0 <1.0.0",
+    "@astrale-os/kernel-api": ">=0.4.5 <1.0.0",
+    "@astrale-os/kernel-client": ">=0.2.2 <1.0.0",
+    "@astrale-os/kernel-core": ">=0.4.3 <1.0.0",
+    "@astrale-os/kernel-dsl": ">=0.1.2 <1.0.0",
     "@astrale-os/kernel-server": ">=0.4.0 <1.0.0",
     "hono": "^4.6.20",
     "jose": "^6.1.3",

package/src/auth/compose.ts

@@ -18,6 +18,18 @@ import {
   unresolvedUnion,
 } from '@astrale-os/kernel-core'
 
+/**
+ * The composed identity expression: union of the caller's delegated access
+ * (a kernel-signed credential leaf) and the function's own identity (self).
+ *
+ * Used both as the grant on outbound kernel calls AND as the delegation
+ * expression when minting a NEXT-HOP credential — the next worker receives
+ * principal = this function, authority = union(caller's delegated, own).
+ */
+export function buildComposedExpr(delegation: Delegation) {
+  return unresolvedUnion(unresolvedCredential(delegation.credential), unresolvedSelf())
+}
+
 /**
  * Build the grant expression that unions the caller's delegated access
  * with the function's own identity.
@@ -26,6 +38,19 @@ import {
  * @returns The unresolved grant object with version and expression
  */
 export function buildComposedGrant(delegation: Delegation) {
-  const expr = unresolvedUnion(unresolvedCredential(delegation.credential), unresolvedSelf())
-  return { grant: createUnresolvedGrant(expr) }
+  return { grant: createUnresolvedGrant(buildComposedExpr(delegation)) }
+}
+
+/**
+ * The SELF-ONLY expression: the function's own identity, nothing delegated.
+ * Used by `selfKernel` sessions (public/webhook handlers acting on their own
+ * authority) — both as the credential grant and as the next-hop delegation.
+ */
+export function buildSelfExpr() {
+  return unresolvedSelf()
+}
+
+/** Self-only grant for `selfKernel` credentials. */
+export function buildSelfGrant() {
+  return { grant: createUnresolvedGrant(buildSelfExpr()) }
 }

package/src/auth/kernel-client.ts

@@ -16,6 +16,7 @@
  */
 
 import type { Delegation } from '@astrale-os/kernel-core'
+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'
@@ -23,11 +24,16 @@ import { ClientSession, type BoundClientSessionView } from '@astrale-os/kernel-c
 
 import type { RemoteIdentityConfig } from './identity'
 
-import { buildComposedGrant } from './compose'
+import { buildComposedExpr, buildComposedGrant, buildSelfExpr, buildSelfGrant } from './compose'
 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.
@@ -65,8 +71,36 @@ export async function bindKernel(
   kernelUrl: string,
   config: RemoteIdentityConfig,
 ): Promise<BoundClientSessionView<FnMap>> {
-  const { grant } = buildComposedGrant(delegation)
-  const composed = await signCredential(
+  return bindSession(kernelUrl, config, buildComposedGrant(delegation).grant, () =>
+    buildComposedExpr(delegation),
+  )
+}
+
+/**
+ * Build a `BoundClientSessionView` authenticated as the FUNCTION'S OWN
+ * identity — no inbound delegation, authority = the function's own grants
+ * only. The seam behind `selfKernel` for public/webhook handlers: an HMAC- or
+ * signature-verified webhook can act on the graph as itself after verifying
+ * the upstream. Next-hop mints delegate self only.
+ */
+export async function bindSelfKernel(
+  kernelUrl: string,
+  config: RemoteIdentityConfig,
+): Promise<BoundClientSessionView<FnMap>> {
+  return bindSession(kernelUrl, config, buildSelfGrant().grant, () => buildSelfExpr())
+}
+
+/**
+ * Shared session construction: sign a credential as this function's identity
+ * carrying `grant`, bind the session to it, and wire the lazy NEXT-HOP mint.
+ */
+async function bindSession(
+  kernelUrl: string,
+  config: RemoteIdentityConfig,
+  grant: unknown,
+  nextHopDelegation: () => UnresolvedIdentityExpr,
+): Promise<BoundClientSessionView<FnMap>> {
+  const credential = await signCredential(
     { grant },
     {
       issuer: config.issuer,
@@ -83,15 +117,21 @@ export async function bindKernel(
     schema: getRegistry(kernelUrl),
     pool: getPool(kernelUrl),
     delegation: {
-      // `@<subject>::mintDelegationCredential` satisfies the syscall's
-      // `self.id === auth.principal` invariant (composed's subject IS the
-      // principal). `skipDelegation` keeps this mint from re-entering itself —
-      // it targets the kernel (same origin), so no delegation is needed.
+      // 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(
-          `@${config.subject}::mintDelegationCredential`,
-          { audience, delegation: { kind: 'identity', self: true }, ttl: DELEGATION_TTL_SECONDS },
-          { credential: composed, skipDelegation: true },
+          `@${selfId}::mintDelegationCredential`,
+          { audience, delegation: nextHopDelegation(), ttl: DELEGATION_TTL_SECONDS },
+          { credential, skipDelegation: true },
         )
         if (typeof envelope !== 'string') {
           throw new Error(
@@ -103,5 +143,57 @@ export async function bindKernel(
       ttl: DELEGATION_TTL_SECONDS,
     },
   })
-  return session.as(composed)
+  return session.as(credential)
+}
+
+/**
+ * Build the `selfKernel` accessor handed to remote-function handlers.
+ * Resolves the kernel URL from the explicit argument or `deps.KERNEL_URL`
+ * (a public request carries no credential, so the parent kernel cannot be
+ * inferred — it must be configured).
+ */
+export function makeSelfKernel(
+  identity: RemoteIdentityConfig,
+  deps: unknown,
+): (kernelUrl?: string) => Promise<BoundClientSessionView<FnMap>> {
+  return async (kernelUrl?: string) => {
+    const url = kernelUrl ?? (deps as { KERNEL_URL?: unknown } | null | undefined)?.KERNEL_URL
+    if (typeof url !== 'string' || url.length === 0) {
+      throw new Error(
+        'selfKernel: no kernel URL — pass one explicitly or set KERNEL_URL in the worker env ' +
+          '(managed deploys set it automatically).',
+      )
+    }
+    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
 }