@every-app/sdk 0.3.0-rc.10 → 0.3.0-rc.12

package/dist/internal/oauthScopes.d.ts

@@ -1,172 +1,60 @@
 /**
- * Scope sets for an `oauth_client` capability with a `scopePolicy`
- * (docs/capabilities.md "OAuth clients"): what an app's manifest entry
- * declares, what that lets the app ask the provider for, how each provider
- * spells what it granted, and which API routes a set unlocks. Pure
- * functions over the registry, shared by the gateway's token-endpoint
- * check, the SDK's local-dev twin of it and, later, the proxy and the
- * outbound Worker. Nothing here reads a secret or a token value.
- */
-import type { OAuthScopeDialect, OAuthScopePolicy } from "./capabilities.js";
-import type { TokenRequest } from "./oauthClient.js";
-/** Scopes by the token they belong to: the bot or only token, and Slack's user token. */
-export interface ScopeList {
-    scopes: string[];
-    userScopes: string[];
-}
-/** What a token response says it granted; a field is present when that kind of token is. */
-export interface GrantedScopes {
-    scopes?: string[];
-    userScopes?: string[];
-}
-/**
- * The scope set names a manifest entry declares, or null when the entry
- * voids its grant: `scopes` missing, not an array, empty, a non-string
- * element, a name listed twice, or any name the policy doesn't offer. An
- * unknown name voids the whole grant rather than narrowing it silently, so
- * a newer CLI's set name reaching an older gateway is refused outright and
- * a message can say so.
- */
-export declare function declaredScopeSets(policy: OAuthScopePolicy, entry: {
-    scopes?: unknown;
-} | undefined): string[] | null;
-/**
- * What an app with `sets` asks the provider for: the sets' scopes in
- * registry order, deduplicated, then `alwaysRequested`. The status hands
- * these out and the authorize URL (Microsoft: the token leg too) carries
- * them verbatim.
- */
-export declare function requestedScopes(policy: OAuthScopePolicy, sets: readonly string[]): ScopeList;
-/**
- * What a token an app with `sets` is handed may carry: the requested
- * scopes and the tolerated ones, in the dialect's canonical spelling so a
- * granted list canonicalised the same way compares exactly.
- */
-export declare function allowedScopes(policy: OAuthScopePolicy, sets: readonly string[]): ScopeList;
-/**
- * Whether a token response body carries a token: an access, refresh or ID
- * token, or Slack's user token under `authed_user`. A 2xx without one
- * (Slack's `ok: false`) is an error the app must see, not a grant.
- */
-export declare function carriesToken(json: unknown): boolean;
-/**
- * The scopes a token response says it granted, canonicalised per dialect,
- * or null when the answer names none for a token it carries, which fails
- * closed: every documented success response of the three providers names
- * them (map-providers: Google and Microsoft `scope`, Slack `scope` and
- * `authed_user.scope`), so a missing field is an answer the gateway can't
- * hold to anything.
- */
-export declare function grantedScopes(policy: OAuthScopePolicy, json: unknown): GrantedScopes | 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 declare function grantedScopesOrRequested(policy: OAuthScopePolicy, json: unknown, requested: ScopeList): GrantedScopes | null;
-/** Why the proxy refuses a held-token call, with what would let it through. */
-export type HeldTokenRefusal = {
-    ok: false;
-    code: "integration_not_connected";
-    /** The declared sets the connection was not granted. */
-    missingSets: string[];
-} | {
-    ok: false;
-    code: "integration_scope_not_allowed" | "integration_method_not_allowed";
-    message: string;
-};
-/**
- * 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.
+ * Scopes for an OAuth provider the Gateway runs the flow for: what a
+ * connect asks for, what a token response says it granted, whether that
+ * is more than was asked, and whether a connection holds what an app
+ * declares. One set of rules for every provider, driven by its spec
+ * (./oauthSpec.ts): the separator, the prefix, the identity scopes and
+ * the tolerated ones. Nothing here names a provider, reads a secret or a
+ * token value.
+ *
+ * An app's `everyapp.config.ts` lists the provider's own scope strings,
+ * short (`gmail.modify`, joined onto the spec's `scopePrefix`) or in
+ * full. Comparison is of the canonical form: percent-decoded, lower case,
+ * the prefix taken off.
  */
-export declare function heldTokenCallAllowed({ policy, declaredSets, connectionSets, hosts, method, upstream, readMethods, writes, }: {
-    policy: OAuthScopePolicy;
-    declaredSets: readonly string[];
-    connectionSets: readonly string[];
-    /** The provider's `api` hosts. */
-    hosts: readonly string[];
-    method: string;
-    upstream: URL;
-    readMethods?: readonly string[];
-    /** Whether `method` is a write the app's grant allows. */
-    writes: boolean;
-}): {
-    ok: true;
-    set: string;
-} | HeldTokenRefusal;
+import type { OAuthFlow } from "./capabilities.js";
+/** The scope rules of a provider's flow. */
+type ScopeRules = Pick<OAuthFlow, "scopeSeparator" | "scopePrefix" | "identityScopes" | "tolerated">;
 /**
- * What `granted` carries beyond `allowed`, per token kind, for a refusal's
- * message and log line: the user token's extras as `user:<scope>`. Both
- * lists are in the dialect's canonical spelling already.
+ * A scope as the provider is asked for it: an app's short scope joined
+ * onto the spec's prefix; a full one (with `://`), one of the spec's own
+ * identity or tolerated scopes, or any scope of a provider without a
+ * prefix, as written.
  */
-export declare function scopeExcess(granted: GrantedScopes, allowed: ScopeList): string[];
+export declare function expandScope(rules: ScopeRules, scope: string): string;
+/** A scope in the one spelling comparisons use: decoded, lower case, without the prefix. */
+export declare function canonicalScope(rules: ScopeRules, scope: string): string;
+/** `scopes` canonical, deduplicated, order kept. */
+export declare function canonicalScopes(rules: ScopeRules, scopes: readonly string[]): string[];
 /**
- * The scopes a token request itself asks for (`scope`, and Slack's
- * `user_scope`, in any case) in its form or JSON body, canonicalised per
- * dialect for comparison with `allowedScopes()`, or null when the body
- * names none. The query string is never read: the gateway refuses a
- * request that puts these there, so only one place decides.
+ * What a connect for an app that declares `declared` asks the provider
+ * for, in the provider's spelling: the app's scopes, then the spec's
+ * identity scopes, each once.
  */
-export declare function requestedTokenScopes(policy: OAuthScopePolicy, request: TokenRequest): GrantedScopes | null;
+export declare function requestedScopes(rules: ScopeRules, declared: readonly string[]): string[];
+/** Scopes joined as the provider's `scope` parameter takes them. */
+export declare function joinScopes(rules: Pick<OAuthFlow, "scopeSeparator">, scopes: readonly string[]): string;
 /**
- * `request` with its `scope`, in any case, as the policy's `requestScope`
- * says: replaced by the requested list of the app's `sets`, dropped, or
- * kept as sent. A separate step after `injectClientCredentials()`, whose
- * re-serialised form or JSON body this edits the same way; any other body
- * is left alone.
+ * The scopes a token response says it granted, canonical. A response
+ * with no `scope` field is taken as granted exactly as `requested` (RFC
+ * 6749 §5.1); one whose `scope` isn't a string is null (refused).
  */
-export declare function rewriteTokenRequestScope(policy: OAuthScopePolicy, sets: readonly string[], request: TokenRequest): TokenRequest;
+export declare function grantedScopes(rules: ScopeRules, body: Record<string, unknown>, requested: readonly string[]): string[] | null;
 /**
- * The declared set that unlocks `method upstream`, or null. Not wired to
- * any live path yet: it becomes the proxy's boundary once the gateway
- * holds tokens, and the outbound Worker's for dispatched apps before that.
- *
- * In order: https only; the host must be on one of the declared sets'
- * routes; the raw pathname is refused when it holds `\`, `//` or `%00`;
- * each raw segment, and each percent-decoding of it while a `%` remains
- * (a provider's layers may each decode once), is refused when it won't
- * decode, holds a control or format character or a backslash, is one of
- * the policy's denied segments in any case, or splits on `/` into a dot
- * segment: `.` or `..`, with or without a `;` parameter (`..;x`), which
- * Google's front end resolves like the bare one. The denied comparison is
- * of the whole segment, because an encoded slash is part of one id to the
- * provider, never a separator: a Search Console site URL whose own path
- * holds `batch` stays matchable, and `2%2FmeasurementProtocolSecrets` is
- * a data stream id that doesn't exist, not the secrets. Then the raw
- * pathname, case preserved, is matched: GET and HEAD need a `paths` entry
- * (exact, or a prefix when it ends in `/`), POST needs a `posts` pattern,
- * and no other method goes through. Matching the raw path is what lets
- * Search Console's `sites/https%3A%2F%2Fexample.com%2F/searchAnalytics/query`
- * match `[^/]+` while `..`, batch tunnels and secrets stay refused however
- * encoded. `X-HTTP-Method-Override`, `access_token` and `token` parameters
- * are the proxy's to strip before it asks; nothing here reads them. The
- * proxy fetches with `redirect: "manual"`: Google answers a dot segment it
- * resolves with a 302 to the resolved path, and following one would carry
- * the token to a path this never matched.
+ * The mint check: what `granted` (canonical) carries beyond `requested`,
+ * the identity scopes and the tolerated ones. Empty means the token may
+ * be kept; anything else and the Gateway drops it.
  */
-export declare function scopeRouteAllows(policy: OAuthScopePolicy, sets: readonly string[], method: string, upstream: URL): string | null;
-/** `scopes` in the dialect's one spelling, deduplicated, order kept. */
+export declare function scopeExcess(rules: ScopeRules, granted: readonly string[], requested: readonly string[]): string[];
 /**
- * `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.
+ * The scopes an app declares that a connection doesn't hold: `held` is
+ * the connection's canonical list, `declared` as the app wrote them.
  */
-export declare function canonicalScopes(dialect: OAuthScopeDialect, scopes: readonly string[]): string[];
+export declare function missingScopes(rules: ScopeRules, held: readonly string[], declared: readonly string[]): string[];
 /**
  * `text` as a JSON object, or null for anything else (an array, a scalar,
- * not JSON). Shared with the gateway's read of a provider's token answer.
+ * not JSON). The gateway's read of a provider's token answer.
  */
 export declare function jsonObject(text: string): Record<string, unknown> | null;
+export {};
 //# sourceMappingURL=oauthScopes.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"oauthScopes.d.ts","sourceRoot":"","sources":["../../src/internal/oauthScopes.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"oauthScopes.d.ts","sourceRoot":"","sources":["../../src/internal/oauthScopes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAEnD,4CAA4C;AAC5C,KAAK,UAAU,GAAG,IAAI,CACpB,SAAS,EACT,gBAAgB,GAAG,aAAa,GAAG,gBAAgB,GAAG,WAAW,CAClE,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAKpE;AAED,4FAA4F;AAC5F,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAYvE;AAED,oDAAoD;AACpD,wBAAgB,eAAe,CAC7B,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,SAAS,MAAM,EAAE,GACxB,MAAM,EAAE,CAOV;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,UAAU,EACjB,QAAQ,EAAE,SAAS,MAAM,EAAE,GAC1B,MAAM,EAAE,CASV;AAED,oEAAoE;AACpE,wBAAgB,UAAU,CACxB,KAAK,EAAE,IAAI,CAAC,SAAS,EAAE,gBAAgB,CAAC,EACxC,MAAM,EAAE,SAAS,MAAM,EAAE,GACxB,MAAM,CAER;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,UAAU,EACjB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,MAAM,EAAE,GAAG,IAAI,CAejB;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,MAAM,EAAE,CAOV;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,UAAU,EACjB,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,QAAQ,EAAE,SAAS,MAAM,EAAE,GAC1B,MAAM,EAAE,CAKV;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CASvE"}