apps 0.0.1-beta.14 → 0.0.1-beta.16

package/types/apps/src/contracts/protocols/oauth.d.ts

@@ -0,0 +1,89 @@
+/** OAuth declarations frozen for host protocols 1 through 5. */
+import { Schema } from "effect";
+/** How an OAuth client authenticates at the token endpoint; raw Basic is an explicit provider compatibility option. */
+export declare const OAuthClientAuth: Schema.Literals<readonly ["none", "client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>;
+export type OAuthClientAuth = typeof OAuthClientAuth.Type;
+/** Machine clients always authenticate; public clients cannot use the client-credentials grant. */
+export declare const OAuthSecretClientAuth: Schema.Literals<readonly ["client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>;
+/** Parameters the host sets on every authorization request; a declaration cannot replace them. */
+export declare const reservedAuthorizationParams: readonly ["response_type", "client_id", "redirect_uri", "state", "scope", "code_challenge", "code_challenge_method", "nonce", "resource", "request", "request_uri"];
+/** A protocol parameter only the host sets on the authorization request. */
+export type ReservedAuthorizationParam = (typeof reservedAuthorizationParams)[number];
+/**
+ * Extra authorization request parameters, such as `access_type: "offline"`. RFC 6749 §3.1
+ * lets services define their own; the protocol and security parameters stay host-owned.
+ */
+export declare const OAuthAuthorizationParams: Schema.$Record<Schema.String, Schema.String>;
+/** How the token endpoint reads requests. RFC 6749 uses a form; some services want JSON. */
+export declare const OAuthTokenRequestFormat: Schema.Literals<readonly ["form", "json"]>;
+export type OAuthTokenRequestFormat = typeof OAuthTokenRequestFormat.Type;
+/**
+ * Where a service nests the grant in its token response, as a dot-separated member path. Slack
+ * returns a user token under `authed_user`.
+ */
+export declare const OAuthTokenResponse: Schema.Struct<{
+    readonly path: Schema.String;
+}>;
+export type OAuthTokenResponse = typeof OAuthTokenResponse.Type;
+/**
+ * OAuth endpoints and protocol choices. Omitted grant means authorization code; clients remain
+ * host-owned. Declared endpoints may name an RFC 7009 `revocationUrl`; discovery reads the
+ * server's `revocation_endpoint` metadata instead.
+ */
+export declare const OAuth2Config: Schema.Union<readonly [Schema.Struct<{
+    readonly discover: Schema.String;
+    readonly authorizationUrl: Schema.optionalKey<Schema.Never>;
+    readonly tokenUrl: Schema.optionalKey<Schema.Never>;
+    readonly revocationUrl: Schema.optionalKey<Schema.Never>;
+    readonly scopes: Schema.optionalKey<Schema.$Array<Schema.String>>;
+    readonly tokenResponse: Schema.optionalKey<Schema.Struct<{
+        readonly path: Schema.String;
+    }>>;
+    readonly grant: Schema.optionalKey<Schema.Literal<"authorization_code">>;
+    readonly authorizationParams: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+    readonly tokenEndpointAuthMethod: Schema.optionalKey<Schema.Literals<readonly ["none", "client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>>;
+    readonly resource: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+    readonly scopeSeparator: Schema.optionalKey<Schema.String>;
+    readonly tokenRequestFormat: Schema.optionalKey<Schema.Literals<readonly ["form", "json"]>>;
+}>, Schema.Struct<{
+    /** Its query is kept; it cannot set protocol parameters or repeat `authorizationParams`. */
+    readonly authorizationUrl: Schema.String;
+    readonly tokenUrl: Schema.String;
+    readonly revocationUrl: Schema.optionalKey<Schema.String>;
+    readonly scopes: Schema.$Array<Schema.String>;
+    /** RFC 8414 issuer identifier. Declared issuers are checked against the callback's `iss`. */
+    readonly issuer: Schema.optionalKey<Schema.String>;
+    readonly discover: Schema.optionalKey<Schema.Never>;
+    readonly tokenResponse: Schema.optionalKey<Schema.Struct<{
+        readonly path: Schema.String;
+    }>>;
+    readonly grant: Schema.optionalKey<Schema.Literal<"authorization_code">>;
+    readonly authorizationParams: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+    readonly tokenEndpointAuthMethod: Schema.optionalKey<Schema.Literals<readonly ["none", "client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>>;
+    readonly resource: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+    readonly scopeSeparator: Schema.optionalKey<Schema.String>;
+    readonly tokenRequestFormat: Schema.optionalKey<Schema.Literals<readonly ["form", "json"]>>;
+}>, Schema.Struct<{
+    readonly tokenEndpointAuthMethod: Schema.Literals<readonly ["client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>;
+    readonly resource: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+    readonly scopeSeparator: Schema.optionalKey<Schema.String>;
+    readonly tokenRequestFormat: Schema.optionalKey<Schema.Literals<readonly ["form", "json"]>>;
+    readonly grant: Schema.Literal<"client_credentials">;
+    readonly discover: Schema.String;
+    readonly authorizationUrl: Schema.optionalKey<Schema.Never>;
+    readonly tokenUrl: Schema.optionalKey<Schema.Never>;
+    readonly revocationUrl: Schema.optionalKey<Schema.Never>;
+    readonly scopes: Schema.optionalKey<Schema.$Array<Schema.String>>;
+}>, Schema.Struct<{
+    readonly tokenEndpointAuthMethod: Schema.Literals<readonly ["client_secret_post", "client_secret_basic", "client_secret_basic_raw"]>;
+    readonly resource: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+    readonly authorizationUrl: Schema.optionalKey<Schema.Never>;
+    readonly discover: Schema.optionalKey<Schema.Never>;
+    readonly scopeSeparator: Schema.optionalKey<Schema.String>;
+    readonly tokenRequestFormat: Schema.optionalKey<Schema.Literals<readonly ["form", "json"]>>;
+    readonly grant: Schema.Literal<"client_credentials">;
+    readonly tokenUrl: Schema.String;
+    readonly revocationUrl: Schema.optionalKey<Schema.String>;
+    readonly scopes: Schema.$Array<Schema.String>;
+}>]>;
+export type OAuth2Config = typeof OAuth2Config.Type;

package/types/apps/src/contracts/provider.d.ts

@@ -42,6 +42,8 @@ export type OAuthTokenResponse = typeof OAuthTokenResponse.Type;
  */
 export declare const OAuth2Config: Schema.Union<readonly [Schema.Struct<{
     readonly discover: Schema.String;
+    /** Fetch this exact metadata document and verify its issuer against discovery. */
+    readonly authorizationServerMetadataUrl: Schema.optionalKey<Schema.String>;
     readonly authorizationUrl: Schema.optionalKey<Schema.Never>;
     readonly tokenUrl: Schema.optionalKey<Schema.Never>;
     readonly revocationUrl: Schema.optionalKey<Schema.Never>;
@@ -64,6 +66,7 @@ export declare const OAuth2Config: Schema.Union<readonly [Schema.Struct<{
     /** RFC 8414 issuer identifier. Declared issuers are checked against the callback's `iss`. */
     readonly issuer: Schema.optionalKey<Schema.String>;
     readonly discover: Schema.optionalKey<Schema.Never>;
+    readonly authorizationServerMetadataUrl: Schema.optionalKey<Schema.Never>;
     readonly tokenResponse: Schema.optionalKey<Schema.Struct<{
         readonly path: Schema.String;
     }>>;
@@ -80,6 +83,8 @@ export declare const OAuth2Config: Schema.Union<readonly [Schema.Struct<{
     readonly tokenRequestFormat: Schema.optionalKey<Schema.Literals<readonly ["form", "json"]>>;
     readonly grant: Schema.Literal<"client_credentials">;
     readonly discover: Schema.String;
+    /** Fetch this exact metadata document and verify its issuer against discovery. */
+    readonly authorizationServerMetadataUrl: Schema.optionalKey<Schema.String>;
     readonly authorizationUrl: Schema.optionalKey<Schema.Never>;
     readonly tokenUrl: Schema.optionalKey<Schema.Never>;
     readonly revocationUrl: Schema.optionalKey<Schema.Never>;
@@ -89,6 +94,7 @@ export declare const OAuth2Config: Schema.Union<readonly [Schema.Struct<{
     readonly resource: Schema.optionalKey<Schema.NullOr<Schema.String>>;
     readonly authorizationUrl: Schema.optionalKey<Schema.Never>;
     readonly discover: Schema.optionalKey<Schema.Never>;
+    readonly authorizationServerMetadataUrl: Schema.optionalKey<Schema.Never>;
     readonly scopeSeparator: Schema.optionalKey<Schema.String>;
     readonly tokenRequestFormat: Schema.optionalKey<Schema.Literals<readonly ["form", "json"]>>;
     readonly grant: Schema.Literal<"client_credentials">;

package/types/apps/src/implementation/operations.d.ts

@@ -79,8 +79,18 @@ export declare const operationOptions: <Input, Output>(options: OperationOptions
     title?: string;
     description?: string;
 };
+/**
+ * Replace a native operation's approval. Property descriptors are copied so an output schema that
+ * a protocol adapter builds only when read stays lazy.
+ */
+export declare const approvedOperation: <Input, Native extends AppOperation<Input, unknown>>(operation: Native, approval: Approval<Input>) => Native;
 /** Attach the same approval function to a generated or shared operation. */
 export declare const withApproval: <Input, Output, Kind extends "query" | "mutation", Context>(operation: Operation<Input, Output, Kind, Context>, approval: Approval<Input>) => Operation<Input, Output, Kind, Context>;
+/**
+ * The advisory hints an operation carries, such as an MCP server's `destructiveHint`. App code
+ * reads them to choose an approval; the framework never infers one from them.
+ */
+export declare const toolAnnotations: (operation: OperationDeclaration<"query" | "mutation", never>) => ToolAnnotations | undefined;
 /** Read operation. External reads are allowed; only database writes are mechanically prohibited. */
 export declare const query: <Input, Output, Context extends AppContext = QueryContext>(options: OperationOptions<Input, Output>, run: (context: Context, input: Input) => Promise<Output>) => Operation<Input, Output, "query", Context>;
 /** Explicit write operation. Database writes roll back on failure; external effects cannot be undone. */

package/types/apps/src/implementation/router.d.ts

@@ -1,6 +1,7 @@
 import { HostedTool } from "../contracts/host.js";
 import type { AppOperation } from "../contracts/operations.js";
 import { RouterMeta, type AppRouter, type DynamicRouter, type RouterIcon } from "../contracts/router.js";
+import type { Approval } from "../approval.js";
 import { type OperationDeclaration, type RouterChild, type RouterDeclaration } from "./operations.js";
 export type { RouterChild, RouterDeclaration } from "./operations.js";
 /** Author metadata for a router. Instructions become a skill named after the router's path. */
@@ -57,3 +58,11 @@ export declare const declaredOperations: (root: AppRouter | undefined, path?: st
     readonly router: string;
     readonly operation: AppOperation;
 }>;
+/**
+ * Choose an approval for each operation a router contains, including tools a dynamic router
+ * resolves later. `policy` receives the operation and its name relative to this router; returning
+ * undefined keeps the operation's own approval. Read hints with `toolAnnotations(operation)`.
+ * Apply it to each account's router before `accountRouter` combines them, so every account keeps
+ * its own tools' hints.
+ */
+export declare const withApprovals: <Query, Mutation>(source: RouterDeclaration<Query, Mutation>, policy: (operation: OperationDeclaration<"query" | "mutation", never>, name: string) => Approval | undefined) => RouterDeclaration<Query, Mutation>;

package/types/apps/src/index.d.ts

@@ -17,7 +17,7 @@ export { type Fields, type Infer, type ObjectSchema, type ObjectValue, type Sche
 export { type AccountCheckContext, type AccountCheckResult, type AccountInfo, type AccountOf, type AuthMethod, type AuthMethodData, type AuthMethods, type ManyAccounts, type Provider, type ReservedAuthorizationParam, } from "./contracts/provider.js";
 export { defineProvider, type ProviderOptions } from "./implementation/provider.js";
 export { accountRouter } from "./implementation/account-router.js";
-export { router, dynamicRouter, type RouterDeclaration, type RouterChild, type RouterOptions, } from "./implementation/router.js";
+export { router, dynamicRouter, withApprovals, type RouterDeclaration, type RouterChild, type RouterOptions, } from "./implementation/router.js";
 export type { RouterIcon } from "./contracts/router.js";
 export { dynamicSkills } from "./implementation/dynamic-skills.js";
 export type { HostedTool as OperationDescription } from "./contracts/host.js";
@@ -72,7 +72,7 @@ export { NotImplemented } from "./contracts/app.js";
 export { ElicitationFailed, type FormElicitation, type ElicitationResponse, type Elicit, } from "./contracts/elicitation.js";
 export { table, defineDatabase, type Table, type DatabaseReader, type Database, type DatabaseDefinition, } from "./implementation/storage.js";
 export { id, userId } from "./implementation/schema.js";
-export { query, mutation, withApproval, type Operation, type OperationOptions, } from "./implementation/operations.js";
+export { query, mutation, withApproval, toolAnnotations, type Operation, type OperationOptions, } from "./implementation/operations.js";
 export type { OperationContext } from "./contracts/operations.js";
 export { workflow, type Workflow, type WorkflowDeclaration } from "./implementation/workflows.js";
 export { NonRetryableError, WorkflowFailure, type WorkflowContext, type WorkflowStepContext, type WorkflowStep, type WorkflowStepOptions, type WorkflowDuration, type WorkflowReads, type WorkflowControls, } from "./contracts/workflows.js";