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

package/dist/internal/oauthScopes.js

@@ -30,7 +30,7 @@ export function declaredScopeSets(policy, entry) {
 export function requestedScopes(policy, sets) {
     const scopes = [];
     const userScopes = [];
-    for (const [, set] of declaredSets(policy, sets)) {
+    for (const [, set] of setsOf(policy, sets)) {
         pushNew(scopes, set.scopes);
         pushNew(userScopes, set.userScopes ?? []);
     }
@@ -103,7 +103,91 @@ export function grantedScopes(policy, json) {
         }
         case "slack":
             return slackGrantedScopes(body);
+        case "space":
+        case "comma": {
+            const scopes = splitScopes(policy.dialect, body["scope"]);
+            return scopes ? { scopes } : null;
+        }
+    }
+}
+/**
+ * What a token response granted, for the Gateway-owned flow: as
+ * {@link grantedScopes}, except that a `space` or `comma` provider that
+ * names no `scope` at all is taken at its word (RFC 6749 §5.1: the field
+ * is optional when the grant matches the request), so `requested` stands.
+ * The three parsed dialects keep failing closed.
+ */
+export function grantedScopesOrRequested(policy, json, requested) {
+    const granted = grantedScopes(policy, json);
+    if (granted)
+        return granted;
+    const body = record(json);
+    if (body &&
+        body["scope"] === undefined &&
+        (policy.dialect === "space" || policy.dialect === "comma")) {
+        return { scopes: canonical(policy.dialect, requested.scopes) };
     }
+    return null;
+}
+/**
+ * Whether an app's call with a held token goes through, and under which
+ * set (docs/design/2026-10-oauth-providers.md section 7). In order: every
+ * set the app declares must be among the connection's (else the person
+ * connects again: `integration_not_connected` with the missing sets); the
+ * host must be one of the provider's `api` hosts; the path passes the
+ * segment rules (`scopeRouteAllows`'s: no batch tunnels, no dot segments,
+ * no denied segments); then a declared set with routes must cover the
+ * call, or a declared set without routes covers its hosts by access: a
+ * read set unlocks `readMethods` (GET and HEAD by default), a write set
+ * every method the provider offers. `writes` says whether the method is
+ * one the grant allows beyond reads, decided by the caller as for an
+ * API-key provider.
+ */
+export function heldTokenCallAllowed({ policy, declaredSets, connectionSets, hosts, method, upstream, readMethods = ["GET", "HEAD"], writes, }) {
+    const missingSets = declaredSets.filter((name) => !connectionSets.includes(name));
+    if (missingSets.length > 0) {
+        return { ok: false, code: "integration_not_connected", missingSets };
+    }
+    if (upstream.protocol !== "https:" || !hosts.includes(upstream.host)) {
+        return {
+            ok: false,
+            code: "integration_scope_not_allowed",
+            message: `${upstream.host} is not a host this provider's token reaches (${hosts.join(", ")}).`,
+        };
+    }
+    if (!safeSegments(policy, upstream.pathname)) {
+        return {
+            ok: false,
+            code: "integration_scope_not_allowed",
+            message: `${upstream.pathname} is a path no scope set unlocks.`,
+        };
+    }
+    const verb = method.toUpperCase();
+    const reads = readMethods.includes(verb);
+    // A set's routes decide first: a read-shaped POST a read set lists
+    // under `posts` (a search, a query) is a read whatever the grant.
+    const routed = scopeRouteAllows(policy, declaredSets, verb, upstream);
+    if (routed)
+        return { ok: true, set: routed };
+    if (!reads && !writes) {
+        return {
+            ok: false,
+            code: "integration_method_not_allowed",
+            message: `${verb} ${upstream.pathname}: calls may use ${readMethods.join(" or ")} with access: "read"; ${verb} needs access: "write" in the app's capabilities entry, on a provider that offers it, or a scope set whose routes list it.`,
+        };
+    }
+    for (const [name, set] of setsOf(policy, declaredSets)) {
+        if (set.routes.length > 0)
+            continue;
+        if (reads || (writes && set.access === "write")) {
+            return { ok: true, set: name };
+        }
+    }
+    return {
+        ok: false,
+        code: "integration_scope_not_allowed",
+        message: `${verb} ${upstream.pathname} is outside the scope sets this app declares (${declaredSets.join(", ")}).`,
+    };
 }
 /**
  * Slack answers with up to two tokens, each with its own scopes: the bot
@@ -243,7 +327,7 @@ export function rewriteTokenRequestScope(policy, sets, request) {
 export function scopeRouteAllows(policy, sets, method, upstream) {
     if (upstream.protocol !== "https:")
         return null;
-    const onHost = declaredSets(policy, sets).flatMap(([name, set]) => set.routes
+    const onHost = setsOf(policy, sets).flatMap(([name, set]) => set.routes
         .filter((route) => route.host === upstream.host)
         .map((route) => [name, route]));
     if (onHost.length === 0)
@@ -318,7 +402,7 @@ function safeSegment(text, denied) {
     return !text.split("/").some((part) => DOT_SEGMENT.test(part));
 }
 /** The policy's sets in registry order, keeping those `names` declares. */
-function declaredSets(policy, names) {
+function setsOf(policy, names) {
     return Object.entries(policy.sets).filter(([name]) => names.includes(name));
 }
 const GOOGLE_ALIASES = new Map([
@@ -327,6 +411,14 @@ const GOOGLE_ALIASES = new Map([
 ]);
 const GRAPH_PREFIX = /^https:\/\/graph\.microsoft\.com\//i;
 /** `scopes` in the dialect's one spelling, deduplicated, order kept. */
+/**
+ * `scopes` in the dialect's canonical spelling (Google's long names,
+ * Microsoft's bare lower-case names), for comparing a set's scopes with
+ * what a token response says it granted.
+ */
+export function canonicalScopes(dialect, scopes) {
+    return canonical(dialect, [...scopes]);
+}
 function canonical(dialect, scopes) {
     return pushNew([], scopes.map((scope) => {
         switch (dialect) {
@@ -335,6 +427,8 @@ function canonical(dialect, scopes) {
             case "microsoft":
                 return scope.replace(GRAPH_PREFIX, "").toLowerCase();
             case "slack":
+            case "space":
+            case "comma":
                 return scope;
         }
     }));
@@ -347,7 +441,7 @@ function canonical(dialect, scopes) {
 function splitScopes(dialect, value) {
     if (typeof value !== "string")
         return null;
-    const separator = dialect === "slack" ? /[,\s]+/ : /\s+/;
+    const separator = dialect === "slack" || dialect === "comma" ? /[,\s]+/ : /\s+/;
     const scopes = canonical(dialect, value.split(separator).filter(Boolean));
     return scopes.length > 0 ? scopes : null;
 }

package/dist/internal/oauthSpec.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The `oauth2-user` half of a provider spec
+ * (docs/design/2026-10-oauth-providers.md section 3): a registered OAuth
+ * provider, or a preset (./oauthPresets.ts), as JSON, turned into the
+ * same {@link OAuthClientCapability} a catalog client is, with a `flow`
+ * the Gateway runs itself. `parseProviderSpec` (./providerSpec.ts) hands
+ * the common fields here once it sees `auth.kind: "oauth2-user"`; nothing
+ * here reads a value: a spec names Gateway settings, never holds one.
+ */
+import { type CapabilityAccess, type OAuthClientCapability } from "./capabilities.js";
+export interface SpecProblem {
+    path: string;
+    message: string;
+}
+/** A scope set's name: `identity`, or `<area>.<access>` (`repo.read`), lowercase. */
+export declare const SCOPE_SET_NAME: RegExp;
+/** Segments no set unlocks on any host: batch tunnels carry whole requests inside. */
+export declare const DEFAULT_DENIED_SEGMENTS: readonly string[];
+/** The fields of `auth` when its kind is `oauth2-user`. */
+export declare const OAUTH_AUTH_FIELDS: readonly ["kind", "authorizeUrl", "tokenUrl", "revokeUrl", "revokeMethod", "clientId", "clientSecret", "inject", "pkce", "scopeDialect", "authorizeParams", "tokenHeaders", "identity"];
+/** The common fields `parseProviderSpec` parsed before handing over. */
+export interface OAuthSpecCommon {
+    id: string;
+    name: string;
+    docs: string;
+    hosts: readonly string[];
+    description?: string;
+    reference?: string;
+    access?: readonly CapabilityAccess[];
+    readMethods?: readonly string[];
+    writeMethods?: readonly string[];
+    hint?: string;
+    example?: string;
+    tags?: readonly string[];
+}
+/** What `parseOAuthUserSpec` returns on success, before the registry's rules. */
+export interface ParsedOAuthSpec {
+    capability: OAuthClientCapability;
+    /** Every host a row's rules must accept: the API hosts and the endpoints'. */
+    hosts: string[];
+}
+/**
+ * Parse the OAuth half of a spec whose `auth.kind` is `oauth2-user`:
+ * `auth` itself, `scopeSets`, `alwaysRequested` and `tolerated`, with
+ * the common fields already parsed. Every problem is reported; on
+ * success the catalog-shaped capability with its `flow`.
+ */
+export declare function parseOAuthUserSpec(input: Record<string, unknown>, common: OAuthSpecCommon, problems: SpecProblem[]): ParsedOAuthSpec | undefined;
+/**
+ * The JSON spec of an OAuth capability that has a `flow` (`provider
+ * show`, a preset's round trip): `parseProviderSpec` of it gives the
+ * capability back. A catalog client without a `flow` has no spec.
+ */
+export declare function oauthSpecOf(id: string, capability: OAuthClientCapability): Record<string, unknown> | null;
+/** The methods a held-token write may use on `capability` beyond its reads. */
+export declare function oauthWriteMethods(capability: OAuthClientCapability): readonly string[];
+/** The methods a read grant may use on `capability` (GET and HEAD unless the spec says). */
+export declare function oauthReadMethods(capability: OAuthClientCapability): readonly string[];
+//# sourceMappingURL=oauthSpec.d.ts.map

package/dist/internal/oauthSpec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauthSpec.d.ts","sourceRoot":"","sources":["../../src/internal/oauthSpec.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,qBAAqB,EAQ3B,MAAM,mBAAmB,CAAC;AAE3B,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,qFAAqF;AACrF,eAAO,MAAM,cAAc,QAC0B,CAAC;AA4BtD,sFAAsF;AACtF,eAAO,MAAM,uBAAuB,EAAE,SAAS,MAAM,EAAwB,CAAC;AAE9E,2DAA2D;AAC3D,eAAO,MAAM,iBAAiB,yLAcpB,CAAC;AAEX,wEAAwE;AACxE,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACrC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B;AAmXD,iFAAiF;AACjF,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,qBAAqB,CAAC;IAClC,8EAA8E;IAC9E,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,MAAM,EAAE,eAAe,EACvB,QAAQ,EAAE,WAAW,EAAE,GACtB,eAAe,GAAG,SAAS,CAqN7B;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,EAAE,EAAE,MAAM,EACV,UAAU,EAAE,qBAAqB,GAChC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAyFhC;AAED,+EAA+E;AAC/E,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,qBAAqB,GAChC,SAAS,MAAM,EAAE,CAEnB;AAED,4FAA4F;AAC5F,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,qBAAqB,GAChC,SAAS,MAAM,EAAE,CAEnB"}