@every-app/sdk 0.2.0 → 0.3.0-rc.1

package/dist/internal/oauthClient.js

@@ -0,0 +1,194 @@
+/**
+ * The `oauth_client` capability's wire rules (docs/capabilities.md "OAuth
+ * clients"), shared by the gateway, which puts the operator's client on an
+ * app's token request, and the SDK's local-dev fallback, which puts the
+ * developer's own on it the same way.
+ */
+import { base64Utf8, oauthClientOrigin, } from "./capabilities.js";
+/** The largest token request body the gateway reads: real ones are a few hundred bytes. */
+export const OAUTH_TOKEN_BODY_LIMIT = 64 * 1024;
+/**
+ * The client `settings` hold for `capability`, or null until every setting
+ * it needs is set: the id, the secret (unless it is a public client), and a
+ * `hostSetting` that is an https origin when it is set at all.
+ */
+export function oauthClientCredentials(capability, settings) {
+    const clientId = settingValue(settings[capability.secrets.clientId]);
+    const secretName = capability.secrets.clientSecret;
+    const clientSecret = secretName
+        ? settingValue(settings[secretName])
+        : undefined;
+    if (!clientId || (secretName && !clientSecret))
+        return null;
+    if (capability.hostSetting && !oauthClientOrigin(capability, settings)) {
+        return null;
+    }
+    return { clientId, ...(clientSecret ? { clientSecret } : {}) };
+}
+function settingValue(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+const FORM = "application/x-www-form-urlencoded";
+const JSON_TYPE = "application/json";
+/**
+ * `request` with `client` put where `rule` says (the form body, HTTP Basic,
+ * the query string or the JSON body), and every client credential the app
+ * sent removed wherever it was: the `Authorization` header, and
+ * `client_id`/`client_secret` (or the rule's names for them, in any case) in
+ * the query string and the body. Bodies are re-serialised from their parsed
+ * values, so a crafted body can't carry a second secret past the parser.
+ * Token requests are form-encoded or JSON; anything else is refused.
+ */
+export function injectClientCredentials(request, rule, client) {
+    const idName = rule.params?.clientId ?? "client_id";
+    const secretName = rule.params?.clientSecret ?? "client_secret";
+    const credentialNames = new Set(["client_id", "client_secret", idName, secretName].map((name) => name.toLowerCase()));
+    const isCredential = (name) => credentialNames.has(name.toLowerCase());
+    const fields = [
+        [idName, client.clientId],
+        ...(client.clientSecret
+            ? [[secretName, client.clientSecret]]
+            : []),
+    ];
+    // The query keeps the app's other fields as they were sent.
+    const url = new URL(request.url);
+    const query = url.search
+        .slice(1)
+        .split("&")
+        .filter((pair) => {
+        const [name] = new URLSearchParams(pair).keys();
+        return pair !== "" && !(name !== undefined && isCredential(name));
+    });
+    if (rule.inject === "query") {
+        query.push(new URLSearchParams(fields).toString());
+    }
+    url.search = query.join("&");
+    const headers = new Headers(request.headers);
+    headers.delete("authorization");
+    headers.delete("content-length");
+    if (rule.inject === "basic") {
+        headers.set("authorization", `Basic ${base64Utf8(`${client.clientId}:${client.clientSecret ?? ""}`)}`);
+    }
+    const type = mediaType(headers.get("content-type"));
+    let body = request.body;
+    if (body === null || body === "") {
+        // Nothing the app sent; the form and JSON rules make the body.
+        if (rule.inject === "form") {
+            headers.set("content-type", FORM);
+            body = new URLSearchParams(fields).toString();
+        }
+        else if (rule.inject === "json") {
+            headers.set("content-type", JSON_TYPE);
+            body = JSON.stringify(Object.fromEntries(fields));
+        }
+    }
+    else if (type === FORM) {
+        if (rule.inject === "json") {
+            return { ok: false, problem: "This token endpoint takes a JSON body." };
+        }
+        const params = new URLSearchParams(body);
+        for (const name of new Set([...params.keys()].filter(isCredential))) {
+            params.delete(name);
+        }
+        if (rule.inject === "form") {
+            for (const [name, value] of fields)
+                params.set(name, value);
+        }
+        body = params.toString();
+    }
+    else if (type === JSON_TYPE) {
+        if (rule.inject === "form") {
+            return {
+                ok: false,
+                problem: `This token endpoint takes a form-encoded body (${FORM}).`,
+            };
+        }
+        const parsed = jsonObject(body);
+        if (!parsed) {
+            return { ok: false, problem: "The body is not a JSON object." };
+        }
+        for (const name of Object.keys(parsed)) {
+            if (isCredential(name))
+                delete parsed[name];
+        }
+        if (rule.inject === "json") {
+            for (const [name, value] of fields)
+                parsed[name] = value;
+        }
+        body = JSON.stringify(parsed);
+    }
+    else {
+        return {
+            ok: false,
+            problem: `A token request's body is form-encoded (${FORM}) or JSON (${JSON_TYPE}).`,
+        };
+    }
+    return { ok: true, url, headers, body };
+}
+/** The grant types logs may name; anything else is logged as `other`. */
+const GRANT_TYPES = new Set([
+    "authorization_code",
+    "refresh_token",
+    "client_credentials",
+    "fb_exchange_token",
+    "ig_exchange_token",
+    "th_exchange_token",
+    "urn:ietf:params:oauth:grant-type:token-exchange",
+]);
+/**
+ * The grants the gateway completes: each ends in a user's own tokens. The
+ * client-credentials grant, and anything else a network serves on the same
+ * endpoint, would mint a token for the gateway's own application instead,
+ * which on Meta, Discord, Twitch or Kick manages the application's
+ * settings, its webhooks and every tenant's tokens.
+ */
+export const USER_BOUND_GRANT_TYPES = new Set([
+    "authorization_code",
+    "refresh_token",
+    "fb_exchange_token",
+    "ig_exchange_token",
+    "th_exchange_token",
+    "urn:ietf:params:oauth:grant-type:token-exchange",
+]);
+/**
+ * A token request's `grant_type` as the app sent it, from its body or query
+ * string, or null when it names none (Meta's code exchange). Never the
+ * request's other fields.
+ */
+export function requestedGrantType(request) {
+    let value = null;
+    const type = mediaType(request.headers.get("content-type"));
+    if (request.body && type === FORM) {
+        value = new URLSearchParams(request.body).get("grant_type");
+    }
+    else if (request.body && type === JSON_TYPE) {
+        value = jsonObject(request.body)?.["grant_type"] ?? null;
+    }
+    value ??= request.url.searchParams.get("grant_type");
+    return typeof value === "string" && value ? value : null;
+}
+/**
+ * A token request's `grant_type` for logs: one of the known grant types,
+ * `other`, or null when it names none.
+ */
+export function tokenGrantType(request) {
+    const value = requestedGrantType(request);
+    if (value === null)
+        return null;
+    return GRANT_TYPES.has(value) ? value : "other";
+}
+/** A Content-Type's media type, lowercased and without parameters. */
+function mediaType(contentType) {
+    return (contentType ?? "").split(";")[0].trim().toLowerCase();
+}
+function jsonObject(text) {
+    try {
+        const value = JSON.parse(text);
+        return value && typeof value === "object" && !Array.isArray(value)
+            ? value
+            : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/internal/oauthScopes.d.ts

@@ -0,0 +1,117 @@
+/**
+ * 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 { 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 `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.
+ */
+export declare function scopeExcess(granted: GrantedScopes, allowed: ScopeList): 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.
+ */
+export declare function requestedTokenScopes(policy: OAuthScopePolicy, request: TokenRequest): GrantedScopes | null;
+/**
+ * `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.
+ */
+export declare function rewriteTokenRequestScope(policy: OAuthScopePolicy, sets: readonly string[], request: TokenRequest): TokenRequest;
+/**
+ * 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.
+ */
+export declare function scopeRouteAllows(policy: OAuthScopePolicy, sets: readonly string[], method: string, upstream: URL): string | null;
+/**
+ * `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.
+ */
+export declare function jsonObject(text: string): Record<string, unknown> | null;
+//# sourceMappingURL=oauthScopes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"oauthScopes.d.ts","sourceRoot":"","sources":["../../src/internal/oauthScopes.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAEV,gBAAgB,EAEjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErD,yFAAyF;AACzF,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,4FAA4F;AAC5F,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,gBAAgB,EACxB,KAAK,EAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,SAAS,GACtC,MAAM,EAAE,GAAG,IAAI,CAejB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,gBAAgB,EACxB,IAAI,EAAE,SAAS,MAAM,EAAE,GACtB,SAAS,CASX;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,gBAAgB,EACxB,IAAI,EAAE,SAAS,MAAM,EAAE,GACtB,SAAS,CASX;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CASnD;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,gBAAgB,EACxB,IAAI,EAAE,OAAO,GACZ,aAAa,GAAG,IAAI,CA6BtB;AA+BD;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE,SAAS,GACjB,MAAM,EAAE,CASV;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,gBAAgB,EACxB,OAAO,EAAE,YAAY,GACpB,aAAa,GAAG,IAAI,CAStB;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,gBAAgB,EACxB,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,EAAE,YAAY,GACpB,YAAY,CA+Bd;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,gBAAgB,EACxB,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,GAAG,GACZ,MAAM,GAAG,IAAI,CAsBf;AAwJD;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAMvE"}