@every-app/sdk 0.3.0-rc.2 → 0.3.0-rc.4

package/dist/server/ai.d.ts

@@ -0,0 +1,45 @@
+/**
+ * `ai()`: the Gateway's default chat model for an app that needs "a model"
+ * rather than one provider (docs/design/2026-10-model-providers.md). The
+ * manifest says `ai: { chat: true }` (or `{ chat: { why } }`); the Gateway's
+ * operator decides which provider and model that is (`everyapp ai
+ * default`, else OpenRouter → Workers AI → OpenAI → …, the first with its
+ * key set), and the app never names either: it sends OpenAI-shaped chat
+ * completions (and embeddings) to `/api/ai/default/v1/…` with `model:
+ * "default"` or no model at all, and the Gateway fills the model in.
+ *
+ * An OpenAI client takes `baseURL` and `fetch` as they are:
+ *
+ *   const { baseURL, fetch, model } = ai({ env, for: request });
+ *   const client = new OpenAI({ baseURL, fetch, apiKey: "gateway-managed" });
+ *   await client.chat.completions.create({ model, messages });
+ *
+ * In local development with no Gateway, the developer's own key in
+ * `.dev.vars` decides the provider by the same order (createGatewayFetch's
+ * fallback). An app that needs one provider in particular keeps listing it
+ * under `providers` and calling `/api/ai/<provider>/…`.
+ */
+import { AI_DEFAULT_MODEL } from "../internal/index.js";
+import { type CreateGatewayFetchOptions } from "./gatewayFetch.js";
+export interface AiClient {
+    /** `http://every-app-gateway.internal/api/ai/default/v1`: an OpenAI client's base URL. */
+    baseURL: string;
+    /** The fetch that reaches the Gateway (or, in dev, the provider directly). */
+    fetch: typeof fetch;
+    /** The model name that means "whatever the Gateway's default is": `default`. */
+    model: typeof AI_DEFAULT_MODEL;
+    /** The default route's chat completions URL, for a plain `fetch`. */
+    chatCompletionsUrl: string;
+    /** The default route's embeddings URL, for a plain `fetch`. */
+    embeddingsUrl: string;
+}
+/** The base URL of the default route, as the SDK and the docs name it. */
+export declare const AI_DEFAULT_BASE_URL = "http://every-app-gateway.internal/api/ai/default/v1";
+/**
+ * The Gateway's default chat model as a client: a base URL, a fetch and
+ * the model name to send. Throws `ConfigurationError` where
+ * `createGatewayFetch` does (no binding and no dev key) and
+ * `AttributionError` where a shared app's call says nobody's.
+ */
+export declare function ai(options: CreateGatewayFetchOptions): AiClient;
+//# sourceMappingURL=ai.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ai.d.ts","sourceRoot":"","sources":["../../src/server/ai.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EAAE,gBAAgB,EAAuB,MAAM,sBAAsB,CAAC;AAC7E,OAAO,EAGL,KAAK,yBAAyB,EAC/B,MAAM,mBAAmB,CAAC;AAE3B,MAAM,WAAW,QAAQ;IACvB,0FAA0F;IAC1F,OAAO,EAAE,MAAM,CAAC;IAChB,8EAA8E;IAC9E,KAAK,EAAE,OAAO,KAAK,CAAC;IACpB,gFAAgF;IAChF,KAAK,EAAE,OAAO,gBAAgB,CAAC;IAC/B,qEAAqE;IACrE,kBAAkB,EAAE,MAAM,CAAC;IAC3B,+DAA+D;IAC/D,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,0EAA0E;AAC1E,eAAO,MAAM,mBAAmB,wDAAuD,CAAC;AAExF;;;;;GAKG;AACH,wBAAgB,EAAE,CAAC,OAAO,EAAE,yBAAyB,GAAG,QAAQ,CAQ/D"}

package/dist/server/ai.js

@@ -0,0 +1,40 @@
+/**
+ * `ai()`: the Gateway's default chat model for an app that needs "a model"
+ * rather than one provider (docs/design/2026-10-model-providers.md). The
+ * manifest says `ai: { chat: true }` (or `{ chat: { why } }`); the Gateway's
+ * operator decides which provider and model that is (`everyapp ai
+ * default`, else OpenRouter → Workers AI → OpenAI → …, the first with its
+ * key set), and the app never names either: it sends OpenAI-shaped chat
+ * completions (and embeddings) to `/api/ai/default/v1/…` with `model:
+ * "default"` or no model at all, and the Gateway fills the model in.
+ *
+ * An OpenAI client takes `baseURL` and `fetch` as they are:
+ *
+ *   const { baseURL, fetch, model } = ai({ env, for: request });
+ *   const client = new OpenAI({ baseURL, fetch, apiKey: "gateway-managed" });
+ *   await client.chat.completions.create({ model, messages });
+ *
+ * In local development with no Gateway, the developer's own key in
+ * `.dev.vars` decides the provider by the same order (createGatewayFetch's
+ * fallback). An app that needs one provider in particular keeps listing it
+ * under `providers` and calling `/api/ai/<provider>/…`.
+ */
+import { AI_DEFAULT_MODEL, AI_DEFAULT_PROVIDER } from "../internal/index.js";
+import { BINDING_ORIGIN, createGatewayFetch, } from "./gatewayFetch.js";
+/** The base URL of the default route, as the SDK and the docs name it. */
+export const AI_DEFAULT_BASE_URL = `${BINDING_ORIGIN}/api/ai/${AI_DEFAULT_PROVIDER}/v1`;
+/**
+ * The Gateway's default chat model as a client: a base URL, a fetch and
+ * the model name to send. Throws `ConfigurationError` where
+ * `createGatewayFetch` does (no binding and no dev key) and
+ * `AttributionError` where a shared app's call says nobody's.
+ */
+export function ai(options) {
+    return {
+        baseURL: AI_DEFAULT_BASE_URL,
+        fetch: createGatewayFetch(options),
+        model: AI_DEFAULT_MODEL,
+        chatCompletionsUrl: `${AI_DEFAULT_BASE_URL}/chat/completions`,
+        embeddingsUrl: `${AI_DEFAULT_BASE_URL}/embeddings`,
+    };
+}

package/dist/server/attribution.d.ts

@@ -1,6 +1,8 @@
 /**
  * Whom a call through the gateway is for, which decides the organization
- * it counts against:
+ * it counts against. Left out, it comes from the request context: the
+ * request `everyApp()` is serving (its person, while the identity is good),
+ * or the organization `withOrganization()` named. Given explicitly:
  *
  *  - the inbound `Request`: its person, by the identity the gateway put on
  *    it (forwarded as is);
@@ -24,11 +26,13 @@ export declare class AttributionError extends Error {
     constructor(message: string);
 }
 /**
- * Check `target` before any call is made: a shared app's Worker must pass
- * the request or name the organization, and anything else passed must be
- * one of the two shapes.
+ * Whom the call is for, checked before any call is made: `target` as the
+ * app passed it, else the request context's answer
+ * ({@link attributionFromContext}; a `RequestContextError` outside every
+ * context). A shared app's Worker must end up with the request or an
+ * organization, and anything passed must be one of the two shapes.
  */
-export declare function checkAttribution(env: object, target: GatewayCallFor | undefined, what: string): void;
+export declare function attributionFor(env: object, target: GatewayCallFor | undefined, what: string): GatewayCallFor | undefined;
 /**
  * Put the call's attribution on its headers: the request's identity, or the
  * background work's organization, and never one the app set itself.

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

@@ -1 +1 @@
-{"version":3,"file":"attribution.d.ts","sourceRoot":"","sources":["../../src/server/attribution.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,cAAc,GACtB,OAAO,GACP;IAAE,UAAU,EAAE,IAAI,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAElD;;;GAGG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,IAAI,0BAA0B;gBAC3B,OAAO,EAAE,MAAM;CAI5B;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,cAAc,GAAG,SAAS,EAClC,IAAI,EAAE,MAAM,GACX,IAAI,CAsBN;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,cAAc,GAAG,SAAS,GACjC,IAAI,CAUN;AASD,0EAA0E;AAC1E,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,OAAO,CAO1D"}
+{"version":3,"file":"attribution.d.ts","sourceRoot":"","sources":["../../src/server/attribution.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,cAAc,GACtB,OAAO,GACP;IAAE,UAAU,EAAE,IAAI,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAElD;;;GAGG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,IAAI,0BAA0B;gBAC3B,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,cAAc,GAAG,SAAS,EAClC,IAAI,EAAE,MAAM,GACX,cAAc,GAAG,SAAS,CAI5B;AA8BD;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,cAAc,GAAG,SAAS,GACjC,IAAI,CAUN;AASD,0EAA0E;AAC1E,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,OAAO,CAO1D"}

package/dist/server/attribution.js

@@ -1,4 +1,5 @@
 import { IDENTITY_HEADER, ORG_HEADER, SHARED_ENV } from "../internal/index.js";
+import { attributionFromContext } from "./context.js";
 /**
  * A gateway call that doesn't say whom it is for where it must: from a
  * shared app's Worker, with neither the request nor an organization.
@@ -11,11 +12,18 @@ export class AttributionError extends Error {
     }
 }
 /**
- * Check `target` before any call is made: a shared app's Worker must pass
- * the request or name the organization, and anything else passed must be
- * one of the two shapes.
+ * Whom the call is for, checked before any call is made: `target` as the
+ * app passed it, else the request context's answer
+ * ({@link attributionFromContext}; a `RequestContextError` outside every
+ * context). A shared app's Worker must end up with the request or an
+ * organization, and anything passed must be one of the two shapes.
  */
-export function checkAttribution(env, target, what) {
+export function attributionFor(env, target, what) {
+    const resolved = target === undefined ? attributionFromContext(what) : target;
+    checkAttribution(env, resolved, what);
+    return resolved;
+}
+function checkAttribution(env, target, what) {
     if (target !== undefined && !isRequest(target)) {
         if (target === null || typeof target !== "object" || !target.background) {
             throw new AttributionError(`${what}: \`for\` is the inbound Request or { background: true, organizationId }.`);

package/dist/server/connectUrl.d.ts

@@ -0,0 +1,21 @@
+import type { ConnectionAccount } from "../internal/index.js";
+export interface ConnectUrlOptions {
+    /** The Worker env: `GATEWAY_URL`, which every deployed Worker and `everyapp dev` set. */
+    env: object;
+    /** The OAuth provider's id (`google-workspace`, `github`). */
+    provider: string;
+    /**
+     * Where to send the person afterwards: the app's own URL (absolute) or
+     * a path on the Gateway. Absent: Settings → Connected accounts.
+     */
+    returnTo?: string;
+    /** Whose connection to make: the person's (default) or the organization's (owner or admin). */
+    account?: ConnectionAccount;
+    /** Scope sets to ask for; absent: the union every active app that lists the provider declares. */
+    sets?: readonly string[];
+}
+/** The path of the connect page for `provider` on the Gateway. */
+export declare function connectPath(provider: string): string;
+/** The absolute URL that starts the Gateway-owned flow for `provider`. */
+export declare function connectUrl({ env, provider, returnTo, account, sets, }: ConnectUrlOptions): string;
+//# sourceMappingURL=connectUrl.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"connectUrl.d.ts","sourceRoot":"","sources":["../../src/server/connectUrl.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAE9D,MAAM,WAAW,iBAAiB;IAChC,yFAAyF;IACzF,GAAG,EAAE,MAAM,CAAC;IACZ,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+FAA+F;IAC/F,OAAO,CAAC,EAAE,iBAAiB,CAAC;IAC5B,kGAAkG;IAClG,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B;AAED,kEAAkE;AAClE,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,0EAA0E;AAC1E,wBAAgB,UAAU,CAAC,EACzB,GAAG,EACH,QAAQ,EACR,QAAQ,EACR,OAAO,EACP,IAAI,GACL,EAAE,iBAAiB,GAAG,MAAM,CAmB5B"}

package/dist/server/connectUrl.js

@@ -0,0 +1,37 @@
+/**
+ * Where an app sends a person to connect an OAuth provider the Gateway
+ * runs the flow for (docs/design/2026-10-oauth-providers.md section 5):
+ * `<gateway>/connect/<id>?return=<back here>&account=<user|organization>`.
+ * The Gateway checks the session, asks the provider for the union of the
+ * sets every active app declares, finishes on its own callback and sends
+ * the browser back to `returnTo`, which must be a path on the Gateway or
+ * an https URL on one of its app hosts (in local dev also localhost).
+ */
+import { ConfigurationError } from "../internal/index.js";
+/** The path of the connect page for `provider` on the Gateway. */
+export function connectPath(provider) {
+    return `/connect/${encodeURIComponent(provider)}`;
+}
+/** The absolute URL that starts the Gateway-owned flow for `provider`. */
+export function connectUrl({ env, provider, returnTo, account, sets, }) {
+    const values = env;
+    const gateway = values["GATEWAY_URL"];
+    if (typeof gateway !== "string" || !gateway.trim()) {
+        throw new ConfigurationError("connectUrl() needs GATEWAY_URL in the Worker env: the deploy sets it, and everyapp dev sets it to the local gateway.");
+    }
+    let base;
+    try {
+        base = new URL(gateway.trim());
+    }
+    catch {
+        throw new ConfigurationError(`GATEWAY_URL isn't a URL: ${gateway}`);
+    }
+    const url = new URL(connectPath(provider), base.origin);
+    if (returnTo)
+        url.searchParams.set("return", returnTo);
+    if (account)
+        url.searchParams.set("account", account);
+    if (sets && sets.length > 0)
+        url.searchParams.set("sets", sets.join(","));
+    return url.toString();
+}

package/dist/server/context.d.ts

@@ -0,0 +1,68 @@
+import type { EveryAppUser } from "../internal/index.js";
+/** What `everyApp()` keeps while it serves one request. */
+export interface ServedRequest {
+    request: Request;
+    /** The verified user, or null on a public route. */
+    user: EveryAppUser | null;
+    /** When the forwarded identity expires (epoch ms); null without one. */
+    expiresAt: number | null;
+}
+/**
+ * A forwarded identity lives 120 seconds. One this close to its expiry could
+ * expire before the Gateway checks it (a 401 the call can't recover from),
+ * so work still running then goes on as the organization's background work.
+ */
+export declare const IDENTITY_EXPIRY_MARGIN_MS = 15000;
+/**
+ * Code `request_context_missing`: `currentUser()` or a Gateway call with
+ * no `for`, outside any request `everyApp()` serves and outside
+ * `withOrganization()`. Work no request started names its organization.
+ */
+export declare class RequestContextError extends Error {
+    readonly code = "request_context_missing";
+    constructor(message: string);
+}
+/**
+ * Code `attribution_organization_mismatch`: `withOrganization()` named
+ * another organization than the request being served belongs to.
+ */
+export declare class OrganizationMismatchError extends Error {
+    readonly code = "attribution_organization_mismatch";
+    constructor(message: string);
+}
+/** Serve `fn` for one request: `everyApp()` calls this; apps don't. */
+export declare function serveRequest<T>(served: ServedRequest, fn: () => T): T;
+/**
+ * Run `fn` as `organizationId`'s background work: every Gateway call made
+ * inside it (and in what it awaits or schedules) is that organization's,
+ * with no person behind it. For a Workflow step, a cron, a queue consumer or
+ * a Durable Object alarm, which no request started. An organization's own
+ * app names its own (`env.EVERY_APP_ORG_ID`); a shared app's Worker names
+ * the one the work is for. Inside a request another organization's person
+ * is driving, it throws {@link OrganizationMismatchError}; inside that
+ * organization's own request, the person stays attributed while their
+ * identity is good.
+ */
+export declare function withOrganization<T>(organizationId: string, fn: () => T): T;
+/**
+ * The verified user of the request being served: an `EveryAppUser`, or
+ * `null` on a public route and inside `withOrganization()`'s background
+ * work. Throws {@link RequestContextError} outside both: there is no one
+ * to be, and a handler that isn't under `everyApp()` is a bug.
+ */
+export declare function currentUser(): EveryAppUser | null;
+/**
+ * Whom a Gateway call made now is for, from the context:
+ *
+ *  - the request being served, while its identity is good;
+ *  - else that organization's background work (the identity is about to
+ *    expire, or `withOrganization()` named it);
+ *  - `undefined` on a public route of an organization's own app, which the
+ *    Gateway attributes to the app's organization; and
+ *  - a {@link RequestContextError} outside every context.
+ */
+export declare function attributionFromContext(what: string, now?: number): Request | {
+    background: true;
+    organizationId?: string;
+} | undefined;
+//# sourceMappingURL=context.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/server/context.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEzD,2DAA2D;AAC3D,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,oDAAoD;IACpD,IAAI,EAAE,YAAY,GAAG,IAAI,CAAC;IAC1B,wEAAwE;IACxE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAUD;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,QAAS,CAAC;AAEhD;;;;GAIG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,IAAI,6BAA6B;gBAC9B,OAAO,EAAE,MAAM;CAI5B;AAED;;;GAGG;AACH,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,QAAQ,CAAC,IAAI,uCAAuC;gBACxC,OAAO,EAAE,MAAM;CAI5B;AAED,uEAAuE;AACvE,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,aAAa,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAErE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,cAAc,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAc1E;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,IAAI,YAAY,GAAG,IAAI,CAQjD;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,GAAG,GAAE,MAAmB,GACvB,OAAO,GAAG;IAAE,UAAU,EAAE,IAAI,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAoBrE"}

package/dist/server/context.js

@@ -0,0 +1,117 @@
+/**
+ * The request context: whom the app is serving, kept for the whole of a
+ * request's work (every `await`, `ctx.waitUntil()`, a streaming body) in an
+ * `AsyncLocalStorage`, which every Every App Worker has (`nodejs_compat`).
+ *
+ * `everyApp()` opens it around the handler and around each tool call, with
+ * the verified user and the request the Gateway forwarded. Deeper in the
+ * app, `currentUser()` reads the user without the request, and every call
+ * back to the Gateway (`integrationFetch`, `ai`, `sendEmail`, `emit`, ...)
+ * is attributed to that person without a `for`.
+ *
+ * Work no request started (a cron, a Workflow step, a queue consumer, a
+ * Durable Object alarm) has no context of its own: it runs under
+ * `withOrganization(organizationId, fn)`, which makes every Gateway call
+ * inside it that organization's background work. A Gateway call with
+ * neither is refused before it is made ({@link RequestContextError}): the
+ * SDK never acts as nobody.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+const scopes = new AsyncLocalStorage();
+/**
+ * A forwarded identity lives 120 seconds. One this close to its expiry could
+ * expire before the Gateway checks it (a 401 the call can't recover from),
+ * so work still running then goes on as the organization's background work.
+ */
+export const IDENTITY_EXPIRY_MARGIN_MS = 15_000;
+/**
+ * Code `request_context_missing`: `currentUser()` or a Gateway call with
+ * no `for`, outside any request `everyApp()` serves and outside
+ * `withOrganization()`. Work no request started names its organization.
+ */
+export class RequestContextError extends Error {
+    code = "request_context_missing";
+    constructor(message) {
+        super(message);
+        this.name = "RequestContextError";
+    }
+}
+/**
+ * Code `attribution_organization_mismatch`: `withOrganization()` named
+ * another organization than the request being served belongs to.
+ */
+export class OrganizationMismatchError extends Error {
+    code = "attribution_organization_mismatch";
+    constructor(message) {
+        super(message);
+        this.name = "OrganizationMismatchError";
+    }
+}
+/** Serve `fn` for one request: `everyApp()` calls this; apps don't. */
+export function serveRequest(served, fn) {
+    return scopes.run({ served }, fn);
+}
+/**
+ * Run `fn` as `organizationId`'s background work: every Gateway call made
+ * inside it (and in what it awaits or schedules) is that organization's,
+ * with no person behind it. For a Workflow step, a cron, a queue consumer or
+ * a Durable Object alarm, which no request started. An organization's own
+ * app names its own (`env.EVERY_APP_ORG_ID`); a shared app's Worker names
+ * the one the work is for. Inside a request another organization's person
+ * is driving, it throws {@link OrganizationMismatchError}; inside that
+ * organization's own request, the person stays attributed while their
+ * identity is good.
+ */
+export function withOrganization(organizationId, fn) {
+    if (typeof organizationId !== "string" || organizationId.trim() === "") {
+        throw new TypeError("withOrganization(organizationId, fn) needs a non-empty organization id (an organization's own app passes env.EVERY_APP_ORG_ID).");
+    }
+    const parent = scopes.getStore();
+    const served = parent?.served;
+    if (served?.user && served.user.orgId !== organizationId) {
+        throw new OrganizationMismatchError(`withOrganization("${organizationId}") was called while serving a request of organization "${served.user.orgId}".`);
+    }
+    return scopes.run({ ...parent, organizationId }, fn);
+}
+/**
+ * The verified user of the request being served: an `EveryAppUser`, or
+ * `null` on a public route and inside `withOrganization()`'s background
+ * work. Throws {@link RequestContextError} outside both: there is no one
+ * to be, and a handler that isn't under `everyApp()` is a bug.
+ */
+export function currentUser() {
+    const scope = scopes.getStore();
+    if (!scope) {
+        throw new RequestContextError("currentUser() was called outside a request everyApp() serves and outside withOrganization(): there is no user here.");
+    }
+    return scope.served?.user ?? null;
+}
+/**
+ * Whom a Gateway call made now is for, from the context:
+ *
+ *  - the request being served, while its identity is good;
+ *  - else that organization's background work (the identity is about to
+ *    expire, or `withOrganization()` named it);
+ *  - `undefined` on a public route of an organization's own app, which the
+ *    Gateway attributes to the app's organization; and
+ *  - a {@link RequestContextError} outside every context.
+ */
+export function attributionFromContext(what, now = Date.now()) {
+    const scope = scopes.getStore();
+    if (!scope) {
+        throw new RequestContextError(`${what} was called with no \`for\`, outside a request everyApp() serves and outside withOrganization(): the call would be nobody's. Pass for: request, or run the work under withOrganization(organizationId, fn).`);
+    }
+    const served = scope.served;
+    if (served?.user) {
+        const fresh = served.expiresAt === null ||
+            now < served.expiresAt - IDENTITY_EXPIRY_MARGIN_MS;
+        // withOrganization() refused any other organization than the request's.
+        if (fresh)
+            return served.request;
+        return { background: true, organizationId: served.user.orgId };
+    }
+    if (scope.organizationId) {
+        return { background: true, organizationId: scope.organizationId };
+    }
+    return undefined;
+}

package/dist/server/emit.d.ts

@@ -59,5 +59,5 @@ export interface EmitOptions {
  * the gateway checks it, printed, and answered `{ id: "dev-…", type }`;
  * nothing is delivered.
  */
-export declare function emit({ env, for: target, event, data, }: EmitOptions): Promise<EmitEventResult>;
+export declare function emit({ env, for: explicitTarget, event, data, }: EmitOptions): Promise<EmitEventResult>;
 //# sourceMappingURL=emit.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"emit.d.ts","sourceRoot":"","sources":["../../src/server/emit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EASL,KAAK,eAAe,EACrB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,kBAAkB,CAAC;AAI1B,MAAM,WAAW,WAAW;IAC1B,8FAA8F;IAC9F,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,IAAI,CAAC,EACzB,GAAG,EACH,GAAG,EAAE,MAAM,EACX,KAAK,EACL,IAAI,GACL,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC,CAoBxC"}
+{"version":3,"file":"emit.d.ts","sourceRoot":"","sources":["../../src/server/emit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EASL,KAAK,eAAe,EACrB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,kBAAkB,CAAC;AAI1B,MAAM,WAAW,WAAW;IAC1B,8FAA8F;IAC9F,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,IAAI,CAAC,EACzB,GAAG,EACH,GAAG,EAAE,cAAc,EACnB,KAAK,EACL,IAAI,GACL,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC,CAoBxC"}

package/dist/server/emit.js

@@ -9,7 +9,7 @@
  * two can't drift.
  */
 import { APP_EVENT_DATA_MAX_BYTES, APP_ID_ENV, ConfigurationError, EVENTS_EMIT_PATH, appEventNameProblem, appEventType, checkEventData, } from "../internal/index.js";
-import { applyAttribution, checkAttribution, } from "./attribution.js";
+import { applyAttribution, attributionFor, } from "./attribution.js";
 import { BINDING_ORIGIN } from "./gatewayFetch.js";
 import { GatewayRefusalError, gatewayRefusal } from "./integrationFetch.js";
 /**
@@ -36,8 +36,8 @@ import { GatewayRefusalError, gatewayRefusal } from "./integrationFetch.js";
  * the gateway checks it, printed, and answered `{ id: "dev-…", type }`;
  * nothing is delivered.
  */
-export async function emit({ env, for: target, event, data, }) {
-    checkAttribution(env, target, "emit");
+export async function emit({ env, for: explicitTarget, event, data, }) {
+    const target = attributionFor(env, explicitTarget, "emit");
     const values = env;
     const binding = values["EVERY_APP_GATEWAY"];
     if (binding) {
@@ -66,7 +66,7 @@ async function emitThroughGateway(binding, target, body) {
         throw new GatewayRefusalError({
             status: response.status,
             code: "event_emit_failed",
-            message: `The Every App gateway answered ${response.status} to the event.`,
+            message: `The EveryApp gateway answered ${response.status} to the event.`,
         });
     }
     return (await response.json());

package/dist/server/everyApp.d.ts

@@ -14,11 +14,21 @@
  * `cloudflare.config.ts` imports from the Worker in dev).
  * It also answers the gateway's internal tools contract
  * (`/__everyapp/tools/*`) for the app's `defineTools()` catalog.
+ *
+ * Around the handler and around each tool call it opens the request
+ * context (context.ts): `currentUser()` reads the user anywhere below, and
+ * every call back to the Gateway is attributed to the request without a
+ * `for`. A deployed Worker is pinned to its organization
+ * (`EVERY_APP_ORG_ID`), and an identity for any other is refused on both
+ * paths. The response leaves without `Set-Cookie`: the perimeter strips
+ * every `Cookie` before a request reaches the app, so a cookie the app's
+ * framework sets could never come back, and one named like the Gateway's
+ * session cookie would lock the person out of the app host.
  */
-import { ConfigurationError, IdentityError, type EveryAppUser, type IdentityResult } from "../internal/index.js";
+import { ConfigurationError, IdentityError, isAdmin, type EveryAppUser, type IdentityResult, type OrgRole } from "../internal/index.js";
 import type { ToolSet } from "./tools.js";
-export { ConfigurationError, IdentityError };
-export type { EveryAppUser, IdentityResult };
+export { ConfigurationError, IdentityError, isAdmin };
+export type { EveryAppUser, IdentityResult, OrgRole };
 /**
  * The runtime's `ExecutionContext`, which `everyApp()` passes to the handler
  * as the Worker received it, so it goes on to Hono's `app.fetch(request,
@@ -60,15 +70,25 @@ interface EveryAppExport<TEnv, TCtx extends ExecutionContextLike> {
 }
 /**
  * Return the verified Every App user for this request, or null for a declared
- * public request. Uses the request cache first, then verifies the identity
- * headers from the app id and public keys configured in env.
+ * public request. `request` is the inbound `Request` or just its `Headers`
+ * (a framework that hands out headers alone needs no made-up Request).
+ * Answers from the request context or the per-request cache first, then
+ * verifies the identity headers from the audience and public keys in env.
+ * Inside a handler `everyApp()` serves, `currentUser()` is the shorter way.
  */
-export declare function getEveryAppUser(request: Request, env: object): Promise<EveryAppUser | null>;
+export declare function getEveryAppUser(request: Request | Headers, env: object): Promise<EveryAppUser | null>;
 /**
  * Return the verified user, or throw the same 401 JSON Response shape as
  * everyApp() when the request is public or unauthenticated.
  */
-export declare function requireEveryAppUser(request: Request, env: object): Promise<EveryAppUser>;
+export declare function requireEveryAppUser(request: Request | Headers, env: object): Promise<EveryAppUser>;
+/**
+ * The user of the request being served (`currentUser()`), or throw the
+ * same 401 JSON Response as `requireEveryAppUser()` on a public route.
+ * Outside a request (`withOrganization()` work, a handler not under
+ * `everyApp()`) it throws `RequestContextError`, as `currentUser()` does.
+ */
+export declare function requireCurrentUser(): EveryAppUser;
 export declare function hasScope(user: EveryAppUser, scope: string): boolean;
 /** Wrap a Worker fetch handler with Every App identity verification. */
 export declare function everyApp<TEnv = Record<string, unknown>, TCtx extends ExecutionContextLike = ExecutionContext>(handler: EveryAppHandler<TEnv, TCtx>, options?: EveryAppOptions): EveryAppExport<TEnv, TCtx>;

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

@@ -1 +1 @@
-{"version":3,"file":"everyApp.d.ts","sourceRoot":"","sources":["../../src/server/everyApp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAGL,kBAAkB,EAElB,aAAa,EAIb,KAAK,YAAY,EACjB,KAAK,cAAc,EAEpB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAG1C,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,CAAC;AAC7C,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,CAAC;AAE7C;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAAG,gBAAgB,CAAC;AAEpD,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,eAAe;IAC9B,iGAAiG;IACjG,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qFAAqF;IACrF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,0BAA0B;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,MAAM,MAAM,eAAe,CACzB,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,IAAI,SAAS,oBAAoB,GAAG,gBAAgB,IAClD,CACF,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,IAAI,EACT,GAAG,EAAE,IAAI,EACT,IAAI,EAAE,YAAY,GAAG,IAAI,KACtB,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;AAElC,UAAU,cAAc,CAAC,IAAI,EAAE,IAAI,SAAS,oBAAoB;IAC9D,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CAClE;AAoHD;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAS9B;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,YAAY,CAAC,CAevB;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAEnE;AAUD,wEAAwE;AACxE,wBAAgB,QAAQ,CACtB,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,IAAI,SAAS,oBAAoB,GAAG,gBAAgB,EAEpD,OAAO,EAAE,eAAe,CAAC,IAAI,EAAE,IAAI,CAAC,EACpC,OAAO,CAAC,EAAE,eAAe,GACxB,cAAc,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AAC9B;;;;GAIG;AACH,wBAAgB,QAAQ,CACtB,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,IAAI,SAAS,oBAAoB,GAAG,gBAAgB,EAEpD,OAAO,EAAE,eAAe,CAAC,IAAI,EAAE,IAAI,CAAC,EACpC,QAAQ,EAAE,oBAAoB,GAAG,SAAS,EAC1C,OAAO,CAAC,EAAE,eAAe,GACxB,cAAc,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC"}
+{"version":3,"file":"everyApp.d.ts","sourceRoot":"","sources":["../../src/server/everyApp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,EAGL,kBAAkB,EAElB,aAAa,EAMb,OAAO,EACP,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,OAAO,EAEb,MAAM,sBAAsB,CAAC;AAE9B,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAG1C,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,OAAO,EAAE,CAAC;AACtD,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,OAAO,EAAE,CAAC;AAEtD;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAAG,gBAAgB,CAAC;AAEpD,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,eAAe;IAC9B,iGAAiG;IACjG,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qFAAqF;IACrF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,0BAA0B;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,MAAM,MAAM,eAAe,CACzB,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,IAAI,SAAS,oBAAoB,GAAG,gBAAgB,IAClD,CACF,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,IAAI,EACT,GAAG,EAAE,IAAI,EACT,IAAI,EAAE,YAAY,GAAG,IAAI,KACtB,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;AAElC,UAAU,cAAc,CAAC,IAAI,EAAE,IAAI,SAAS,oBAAoB;IAC9D,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CAClE;AAuKD;;;;;;;GAOG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,OAAO,GAAG,OAAO,EAC1B,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAW9B;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,OAAO,GAAG,OAAO,EAC1B,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,YAAY,CAAC,CAevB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,IAAI,YAAY,CAMjD;AA0BD,wBAAgB,QAAQ,CAAC,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAEnE;AAUD,wEAAwE;AACxE,wBAAgB,QAAQ,CACtB,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,IAAI,SAAS,oBAAoB,GAAG,gBAAgB,EAEpD,OAAO,EAAE,eAAe,CAAC,IAAI,EAAE,IAAI,CAAC,EACpC,OAAO,CAAC,EAAE,eAAe,GACxB,cAAc,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AAC9B;;;;GAIG;AACH,wBAAgB,QAAQ,CACtB,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,IAAI,SAAS,oBAAoB,GAAG,gBAAgB,EAEpD,OAAO,EAAE,eAAe,CAAC,IAAI,EAAE,IAAI,CAAC,EACpC,QAAQ,EAAE,oBAAoB,GAAG,SAAS,EAC1C,OAAO,CAAC,EAAE,eAAe,GACxB,cAAc,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC"}