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

package/dist/internal/oauthSpec.d.ts

@@ -0,0 +1,102 @@
+/**
+ * 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, type OAuthScopeSet } 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[];
+}
+/**
+ * One scope set (`{ label, access, scopes, userScopes?, routes? }`) at
+ * `at`, its routes on `hosts` alone; undefined when a field is wrong,
+ * every problem reported. `overlay`: a set added to a built-in client
+ * must name a scope and say what it unlocks (a set with no routes unlocks
+ * nothing on the held-token path); a spec's own set may leave both empty
+ * (Notion's sets carry no scope string).
+ */
+export declare function parseScopeSet(raw: unknown, at: string, hosts: readonly string[], problems: SpecProblem[], { overlay }?: {
+    overlay?: boolean;
+}): OAuthScopeSet | undefined;
+/** What `parseScopeSetOverlay` returns. */
+export type ParsedScopeSetOverlay = {
+    ok: true;
+    name: string;
+    set: OAuthScopeSet;
+} | {
+    ok: false;
+    problems: SpecProblem[];
+};
+/**
+ * A scope set an operator adds to a built-in OAuth client
+ * (`everyapp provider scope-set add google-workspace gmail-send.json`):
+ * `{ "name": "gmail.send", "label", "access", "scopes", "routes" }`, held
+ * to the rules a built-in set is (the set's shape, routes on the client's
+ * `api` hosts alone, anchored `posts`) plus two of its own: `access` is
+ * said outright (a write set is never implied by its scopes) and `routes`
+ * is required. A `provider` field, when present, must be `id`. The name
+ * may not be one of the client's own sets: an overlay adds, never
+ * replaces. Nothing here reads a value.
+ */
+export declare function parseScopeSetOverlay(input: unknown, client: {
+    id: string;
+    capability: OAuthClientCapability;
+}): ParsedScopeSetOverlay;
+/**
+ * `capability` with `sets` added to its scope policy: the sets after the
+ * client's own, in the order given, and each set's scopes added to the
+ * authorize URL's list (what the operator's client must be allowed), as
+ * `parseOAuthUserSpec` builds it. A name the client already has is left
+ * as the client's (the registry refuses such an overlay before this).
+ */
+export declare function withScopeSets(capability: OAuthClientCapability, sets: Readonly<Record<string, OAuthScopeSet>>): OAuthClientCapability;
+/** 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":"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"}