runline 0.37.0 → 0.39.0

package/dist/credentials/transport.js

@@ -3,9 +3,10 @@ import { Check } from "typebox/value";
 import { AuthError } from "../auth/errors.js";
 import { acquireOAuth2ClientToken, acquireOAuth2JwtToken, acquireOAuth2PasswordToken, refreshOAuth2Token, } from "../auth/oauth2.js";
 import { assumeAwsRole, awsAccessKey } from "./aws.js";
+import { applySetCookies, cookieFor, cookieHeader, liveCookies, } from "./cookies.js";
 import { sendResource } from "./http.js";
 import { bodyFields, bodyFormat, bounded, headerName, injectedFields, injectedHeaders, injectedParams, injectedPointers, placementsFor, pointerSlot, refuseCredentialParams, resourceUrl, secret, TARGET_RESPONSE_LIMIT_BYTES, TARGET_TIMEOUT_LIMIT_MS, TRANSPORT_HEADERS, targetBase, targetOf, } from "./policy.js";
-import { OAuthGrantSchema, validateCredential, } from "./registry.js";
+import { CookieSessionSchema, OAuthGrantSchema, validateCredential, } from "./registry.js";
 import { canonicalQuery, signSigV4 } from "./sigv4.js";
 function boundSnapshot(binding, method, snapshot) {
     if (snapshot.name !== binding.identity.name ||
@@ -29,6 +30,67 @@ function grantFrom(method, config) {
         throw new AuthError("unsupported_operation");
     return result;
 }
+function cookieSessionFrom(auth, config) {
+    const session = config[auth.field];
+    if (session === undefined)
+        return undefined;
+    if (!Check(CookieSessionSchema, session))
+        throw new AuthError("invalid_credentials");
+    return session;
+}
+/** Methods that change state, on which a CSRF header is sent. */
+function unsafe(method) {
+    return method !== "GET" && method !== "HEAD";
+}
+/** Signs with the jar's cookies for the request's URL, and the CSRF header on an unsafe one. */
+function cookieSigner(auth, cookies) {
+    return ({ method, headers, url }) => {
+        const now = Date.now();
+        const cookie = cookieHeader(cookies, url, now);
+        if (cookie)
+            headers.set("cookie", cookie);
+        if (auth.csrf && unsafe(method)) {
+            const token = cookieFor(cookies, auth.csrf.cookie, url, now);
+            if (token)
+                headers.set(headerName(auth.csrf.header), token);
+        }
+    };
+}
+/** Whether a Location, read against the request's `url`, falls beneath a declared login path. */
+function toLogin(auth, loginTarget, location, url) {
+    if (!location || !auth.rejection.loginPaths)
+        return false;
+    let next;
+    try {
+        next = new URL(location, url);
+    }
+    catch {
+        return false;
+    }
+    return auth.rejection.loginPaths.some((path) => {
+        const login = resourceUrl(loginTarget, path);
+        return (next.origin === login.origin && next.pathname.startsWith(login.pathname));
+    });
+}
+/**
+ * How a response shows a cookie session was rejected, by the method's
+ * declared signals: its status, a redirect to a login path, or a body
+ * marker on an HTML answer. Null when it shows none.
+ */
+async function sessionRejection(auth, loginTarget, response, url) {
+    const { statuses, marker } = auth.rejection;
+    if (statuses?.includes(response.status))
+        return "status";
+    if (toLogin(auth, loginTarget, response.headers.get("location"), url))
+        return "redirect";
+    if (marker &&
+        response.status >= 200 &&
+        response.status < 300 &&
+        (response.headers.get("content-type") ?? "").includes("text/html") &&
+        (await response.clone().text()).includes(marker))
+        return "marker";
+    return null;
+}
 function pinBinding(selection) {
     return {
         ...selection,
@@ -313,6 +375,118 @@ export class CredentialTransport {
             },
         });
     }
+    /**
+     * A cookie session logged in under the connection's update ownership, so
+     * parallel calls on an expired session log in once: one another caller
+     * committed meanwhile is kept. With `rejected`, the jar sent at
+     * `observedRevision` was refused and only a newer login is kept.
+     */
+    loginSession(binding, method, observedRevision, rejected = false) {
+        const auth = method.authentication;
+        if (auth.kind !== "cookie")
+            throw new AuthError("invalid_definition");
+        return this.commitIssued(binding, method, {
+            field: auth.field,
+            read: (config) => cookieSessionFrom(auth, config),
+            usable: (previous) => !!previous &&
+                liveCookies(previous.cookies, Date.now()).length > 0 &&
+                (!rejected || previous.revision !== observedRevision),
+            issue: (previous) => this.logIn(auth, method, binding, previous),
+        });
+    }
+    /**
+     * The declared login: a preflight GET when declared, then the owner's
+     * POST, both carrying the jar and absorbing what they set. The jar is
+     * merged into, never replaced, so a device-trust cookie survives. A
+     * login refused by status is `provider_rejected` with it; one the app
+     * answers with a rejection signal, or that leaves no cookie, is
+     * `reconnect_required`. The password goes in this one request only.
+     */
+    async logIn(auth, method, binding, previous) {
+        const owner = binding.resourceOwner;
+        if (!owner?.username || !owner.password)
+            throw new AuthError("invalid_credentials");
+        const { login } = auth;
+        const target = targetOf(method, login.target);
+        if (!target)
+            throw new AuthError("invalid_definition");
+        let cookies = liveCookies(previous?.cookies ?? [], Date.now());
+        const exchange = async (path, verb, body) => {
+            const url = resourceUrl(target, path);
+            const headers = new Headers({ accept: "*/*" });
+            if (body)
+                headers.set("content-type", body.type);
+            const sign = cookieSigner(auth, cookies);
+            sign({ method: verb, headers, url, base: targetBase(target).pathname });
+            let set = [];
+            const response = await sendResource(url.toString(), verb, headers, body?.bytes, {
+                fetch: this.options.fetch,
+                timeoutMs: this.options.timeoutMs,
+                maxResponseBytes: this.options.maxResponseBytes,
+                redirect: () => true,
+                setCookie: (values) => {
+                    set = values;
+                },
+            });
+            cookies = applySetCookies(cookies, set, url, Date.now());
+            return { response, url };
+        };
+        if (login.preflight !== undefined) {
+            const { response } = await exchange(login.preflight, "GET");
+            if (response.status >= 400)
+                throw new AuthError("provider_rejected", response.status);
+        }
+        const fields = {
+            ...login.parameters,
+            [login.fields?.username ?? "username"]: owner.username,
+            [login.fields?.password ?? "password"]: owner.password,
+        };
+        const body = login.encoding === "json"
+            ? {
+                type: "application/json",
+                bytes: Buffer.from(JSON.stringify(fields)),
+            }
+            : {
+                type: "application/x-www-form-urlencoded",
+                bytes: Buffer.from(new URLSearchParams(fields).toString()),
+            };
+        const { response, url } = await exchange(login.path, "POST", body);
+        if (response.status >= 400)
+            throw new AuthError("provider_rejected", response.status);
+        if ((await sessionRejection(auth, target, response, url)) ||
+            !liveCookies(cookies, Date.now()).length)
+            throw new AuthError("reconnect_required");
+        return { cookies, revision: randomUUID() };
+    }
+    /**
+     * What a response of the session sent at `revision` set, merged into the
+     * stored jar: a rotated, added or deleted cookie. Only while the jar is
+     * still that login's, so a stale response never undoes a newer login.
+     * Best effort: a store that fails leaves the response standing, and the
+     * session is renewed when it is next rejected.
+     */
+    async absorb(binding, method, revision, values, url) {
+        const auth = method.authentication;
+        if (auth.kind !== "cookie" || !values.length)
+            return;
+        try {
+            await binding.connection.update(async (current) => {
+                validateCredential(method, current);
+                const stored = cookieSessionFrom(auth, current);
+                if (stored?.revision !== revision)
+                    return undefined;
+                return {
+                    [auth.field]: {
+                        cookies: applySetCookies(stored.cookies, values, url, Date.now()),
+                        revision,
+                    },
+                };
+            });
+        }
+        catch {
+            // The response stands; the jar catches up at the next rejection.
+        }
+    }
     /** A role session for the binding's `awsRole`, assumed with the stored key. */
     renewAwsSession(binding, method, observedRevision) {
         const auth = method.authentication;
@@ -442,9 +616,17 @@ export class CredentialTransport {
         }
         const replay = input.retry !== "never" &&
             (verb === "GET" || verb === "HEAD" || input.idempotencyKey !== undefined);
+        // A rejected credential is dead whether or not this request may be sent
+        // again, so it is renewed either way and the next call signs with the
+        // renewal. Only a replayable request is sent again, exactly once; any
+        // other is answered with its rejection.
+        const afterRejection = async (rejection, renew, resend) => {
+            const renewed = await renew();
+            return replay ? resend(renewed) : rejection;
+        };
         const base = targetBase(target).pathname;
-        let { sign, grant } = await this.authorize(binding, method, input.target);
-        const send = async (signer) => {
+        const { sign, grant, session } = await this.authorize(binding, method, input.target);
+        const send = async (signer, cookies) => {
             const outgoing = {
                 method: verb,
                 headers: new Headers(headers),
@@ -458,17 +640,43 @@ export class CredentialTransport {
                 timeoutMs: Math.min(target.timeoutMs ?? this.options.timeoutMs, this.options.maxTargetTimeoutMs),
                 maxResponseBytes: Math.min(target.maxResponseBytes ?? this.options.maxResponseBytes, this.options.maxTargetResponseBytes),
                 resumableUpload: target.resumableUpload,
+                ...cookies,
             });
         };
+        if (auth.kind === "cookie" && session) {
+            const loginTarget = targetOf(method, auth.login.target);
+            if (!loginTarget)
+                throw new AuthError("invalid_definition");
+            const attempt = async (current) => {
+                let set = [];
+                const response = await send(cookieSigner(auth, current.cookies), {
+                    redirect: (location) => toLogin(auth, loginTarget, location, url),
+                    setCookie: (values) => {
+                        set = values;
+                    },
+                });
+                await this.absorb(binding, method, current.revision, set, url);
+                const rejection = await sessionRejection(auth, loginTarget, response, url);
+                // A rejection by redirect or marker reads as the 401 it means; one
+                // by status keeps the app's own answer.
+                return {
+                    rejection,
+                    response: rejection === "redirect" || rejection === "marker"
+                        ? new Response(null, { status: 401 })
+                        : response,
+                };
+            };
+            const first = await attempt(session);
+            if (!first.rejection)
+                return first.response;
+            return afterRejection(first.response, () => this.loginSession(binding, method, session.revision, true), async (renewed) => (await attempt(renewed)).response);
+        }
         const first = await send(sign);
         if (auth.kind !== "oauth2" ||
             !grant ||
-            !replay ||
             first.status !== (auth.rejectionStatus ?? 401))
             return first;
-        // Exactly one replay, only after durable renewal (or a newer committed revision).
-        grant = await this.renew(binding, method, grant.revision, true);
-        return send(bearer(secret(grant.tokens.accessToken)));
+        return afterRejection(first, () => this.renew(binding, method, grant.revision, true), (renewed) => send(bearer(secret(renewed.tokens.accessToken))));
     }
     /**
      * A socket target's URL, signed by its query placements, for a host's
@@ -521,6 +729,13 @@ export class CredentialTransport {
         const auth = method.authentication;
         if (auth.kind === "none")
             return { sign: () => { } };
+        if (auth.kind === "cookie") {
+            const stored = cookieSessionFrom(auth, config);
+            const session = stored && liveCookies(stored.cookies, Date.now()).length
+                ? stored
+                : await this.loginSession(binding, method, stored?.revision);
+            return { sign: cookieSigner(auth, session.cookies), session };
+        }
         if (auth.kind === "awsSigV4") {
             const scope = targetOf(method, target)?.aws;
             if (!scope)

package/dist/credentials/types.d.ts

@@ -139,7 +139,8 @@ export type SecretPlacement = ({
  * How a request is signed. `field` names the one top-level config field
  * holding the secret: for `static`, a record of the named `parts`
  * (`staticSecretSchema(parts)`), each sent through its placements; for
- * `oauth2`, a revisioned OAuthGrant; for `awsSigV4`, an AWS access key.
+ * `oauth2`, a revisioned OAuthGrant; for `awsSigV4`, an AWS access key;
+ * for `cookie`, a revisioned `CookieSession` jar.
  * `none` signs nothing: the method of a connection that holds no optional
  * credential, still pinned to its targets.
  */
@@ -190,7 +191,79 @@ export type CredentialAuthentication = {
     assumeRole?: {
         sessionField: string;
     };
+} | {
+    /**
+     * A web app's cookie session. The transport logs in with the
+     * binding's `resourceOwner` as `login` declares, keeps every cookie
+     * the method's targets set in a jar in `field` (`CookieSessionSchema`),
+     * sends each only where RFC 6265 matches it, and logs in again when a
+     * response shows the session was rejected. The plugin never sees the
+     * password, the jar, or a `Set-Cookie`.
+     */
+    kind: "cookie";
+    field: string;
+    login: CookieLogin;
+    rejection: CookieRejection;
+    /**
+     * Cookie-based CSRF (Django's `csrftoken`, `XSRF-TOKEN`): the named
+     * cookie's value is copied into `header` on every unsafe request, the
+     * login included. The header is reserved: callers never set it.
+     */
+    csrf?: {
+        cookie: string;
+        header: string;
+    };
 };
+/**
+ * How the transport logs in: an optional preflight GET (a CSRF cookie, a
+ * session to log into), then one POST of the owner's username and password
+ * under the app's own field names, beside fixed `parameters`. Both go to
+ * `target` and carry the jar, so a device-trust cookie rides along.
+ */
+export interface CookieLogin {
+    target: string;
+    /** Relative to the target's base, as a request path is. */
+    path: string;
+    encoding: "form" | "json";
+    /** The app's names for the owner's fields; `username` and `password` when absent. */
+    fields?: {
+        username?: string;
+        password?: string;
+    };
+    /** Fixed extra fields, such as `remember: "1"`. Never a secret. */
+    parameters?: Record<string, string>;
+    /** A path on `target` to GET before the POST. */
+    preflight?: string;
+}
+/**
+ * What a rejected session looks like, at least one of: a status; a 3xx
+ * whose Location falls under one of `loginPaths` (relative to the login
+ * target, as `login.path` is); or a 2xx HTML answer containing `marker`.
+ */
+export interface CookieRejection {
+    /** 4xx statuses, such as 401, 403, Laravel's 419 or IIS's 440. */
+    statuses?: number[];
+    loginPaths?: string[];
+    marker?: string;
+}
+/** One cookie in a session's jar, as RFC 6265 stores it. */
+export interface StoredCookie {
+    name: string;
+    value: string;
+    /** Lowercased: the exact host when `hostOnly`, else the Domain attribute. */
+    domain: string;
+    hostOnly: boolean;
+    path: string;
+    secure: boolean;
+    httpOnly: boolean;
+    /** Milliseconds since epoch; absent for a session cookie, kept until replaced. */
+    expiresAt?: number;
+}
+/** A cookie jar as stored. `revision` changes on every login, never on a rotated cookie. */
+export interface CookieSession {
+    cookies: StoredCookie[];
+    revision: string;
+}
 export interface CredentialProbe {
     target: string;
     /** Fixed relative path, including any fixed query. No expressions or callbacks. */

package/dist/index.d.ts

@@ -16,13 +16,13 @@ export { awsEndpoint, awsRegion, parseAwsXml } from "./credentials/aws.js";
 export type { AwsCredentialSpec } from "./credentials/aws-plugin.js";
 export { awsCredential, awsFailed, awsJson, awsList, awsQuery, awsTarget, } from "./credentials/aws-plugin.js";
 export { brokerFor } from "./credentials/broker.js";
-export { downloadResource } from "./credentials/http.js";
+export { downloadResource, type PresignedRequestOptions, presignedRequest, } from "./credentials/http.js";
 export type { CredentialCall, EmptyAnswer, ErrorEnvelope, StaticCredentialSpec, } from "./credentials/plugin.js";
-export { answerFailed, configChoice, configFlag, credentialJson, credentialOk, credentialRequest, credentialSocketUrl, errorIdentifier, failureMessage, grantSchema, graphqlFailed, hostLabel, httpsBase, jsonAnswer, jsonOrAcknowledged, multipartBody, pathSegment, pathSegments, pathWithin, refuseUnderHost, requestFailed, responseFailed, slashEncodedSegment, staticCredential, } from "./credentials/plugin.js";
-export { AwsAccessKeySchema, AwsSessionSchema, CredentialRegistry, OAuthGrantSchema, OAuthTokensSchema, staticSecretSchema, validateCredential, } from "./credentials/registry.js";
+export { answerFailed, configChoice, configFlag, cookieSessionSchema, credentialJson, credentialOk, credentialRequest, credentialSocketUrl, errorIdentifier, failureMessage, grantSchema, graphqlFailed, hostLabel, httpsBase, jsonAnswer, jsonOrAcknowledged, multipartBody, pathSegment, pathSegments, pathWithin, refuseUnderHost, requestFailed, responseFailed, slashEncodedSegment, staticCredential, } from "./credentials/plugin.js";
+export { AwsAccessKeySchema, AwsSessionSchema, CookieSessionSchema, CredentialRegistry, OAuthGrantSchema, OAuthTokensSchema, StoredCookieSchema, staticSecretSchema, validateCredential, } from "./credentials/registry.js";
 export type { AuthenticatedRequest, CredentialBroker, CredentialBrokerCall, CredentialTransportOptions, SocketRequest, } from "./credentials/transport.js";
 export { CredentialTransport } from "./credentials/transport.js";
-export type { AwsAccessKey, AwsRole, AwsScope, AwsSession, CredentialAuthentication, CredentialBinding, CredentialDeclaration, CredentialMethod, CredentialProbe, CredentialProbeResult, CredentialSelection, CredentialTarget, CredentialType, HttpMethod, LocalSecretPart, LocalSecretSource, OAuthGrant, SecretPlacement, } from "./credentials/types.js";
+export type { AwsAccessKey, AwsRole, AwsScope, AwsSession, CookieLogin, CookieRejection, CookieSession, CredentialAuthentication, CredentialBinding, CredentialDeclaration, CredentialMethod, CredentialProbe, CredentialProbeResult, CredentialSelection, CredentialTarget, CredentialType, HttpMethod, LocalSecretPart, LocalSecretSource, OAuthGrant, SecretPlacement, StoredCookie, } from "./credentials/types.js";
 export type { ActionDefinition, PluginFunction, RunlinePluginAPI, } from "./plugin/api.js";
 export { createPluginAPI, isPluginFunction, resolvePluginExport, } from "./plugin/api.js";
 export type { InstalledPlugin, PluginSource } from "./plugin/installer.js";

package/dist/index.js

@@ -10,9 +10,9 @@ export { buildAuthUrl, exchangeAuthCode, generatePKCE, OAUTH_CALLBACK_PORT, OAUT
 export { awsEndpoint, awsRegion, parseAwsXml } from "./credentials/aws.js";
 export { awsCredential, awsFailed, awsJson, awsList, awsQuery, awsTarget, } from "./credentials/aws-plugin.js";
 export { brokerFor } from "./credentials/broker.js";
-export { downloadResource } from "./credentials/http.js";
-export { answerFailed, configChoice, configFlag, credentialJson, credentialOk, credentialRequest, credentialSocketUrl, errorIdentifier, failureMessage, grantSchema, graphqlFailed, hostLabel, httpsBase, jsonAnswer, jsonOrAcknowledged, multipartBody, pathSegment, pathSegments, pathWithin, refuseUnderHost, requestFailed, responseFailed, slashEncodedSegment, staticCredential, } from "./credentials/plugin.js";
-export { AwsAccessKeySchema, AwsSessionSchema, CredentialRegistry, OAuthGrantSchema, OAuthTokensSchema, staticSecretSchema, validateCredential, } from "./credentials/registry.js";
+export { downloadResource, presignedRequest, } from "./credentials/http.js";
+export { answerFailed, configChoice, configFlag, cookieSessionSchema, credentialJson, credentialOk, credentialRequest, credentialSocketUrl, errorIdentifier, failureMessage, grantSchema, graphqlFailed, hostLabel, httpsBase, jsonAnswer, jsonOrAcknowledged, multipartBody, pathSegment, pathSegments, pathWithin, refuseUnderHost, requestFailed, responseFailed, slashEncodedSegment, staticCredential, } from "./credentials/plugin.js";
+export { AwsAccessKeySchema, AwsSessionSchema, CookieSessionSchema, CredentialRegistry, OAuthGrantSchema, OAuthTokensSchema, StoredCookieSchema, staticSecretSchema, validateCredential, } from "./credentials/registry.js";
 export { CredentialTransport } from "./credentials/transport.js";
 export { createPluginAPI, isPluginFunction, resolvePluginExport, } from "./plugin/api.js";
 export { installPlugin, listInstalled, parsePluginSource, removePlugin, } from "./plugin/installer.js";

package/dist/plugins/_shared/attachments.js

@@ -0,0 +1,97 @@
+import { basename } from "node:path";
+import * as t from "typebox";
+import { DownloadedFile, standardBase64 } from "./base64.js";
+import { readLocalFile } from "./localFile.js";
+const STRICT = { additionalProperties: false };
+const id = t.String({ minLength: 1, pattern: "\\S" });
+/** What any attachment may say about itself, whatever its bytes are. */
+export const attachmentMetadata = {
+    name: t.Optional(t.String({ ...id, description: "File name; defaults to the path's name." })),
+    mimeType: t.Optional(t.String({ ...id, description: "MIME type, e.g. application/pdf." })),
+    inline: t.Optional(t.Boolean({
+        description: "Embed in the HTML body, referenced as cid:<contentId>, instead of attaching.",
+    })),
+    contentId: t.Optional(t.String({ ...id, description: "Content-ID for inline images." })),
+};
+/**
+ * An attachment's bytes, given one way each and named as gmail and
+ * googleDrive name them: `contentBase64` (base64, or a
+ * googleDrive.file.download result passed straight through),
+ * `contentPath` (a file on the runline host) or `content` (UTF-8 text).
+ * `sizeNote` states the plugin's own limit.
+ */
+export function attachmentSources(sizeNote) {
+    return [
+        t.Object({
+            ...attachmentMetadata,
+            contentBase64: t.Union([t.String(), DownloadedFile], {
+                description: `Base64 bytes (standard or base64url; padding and whitespace normalized), or a googleDrive.file.download result, whose name and mimeType are used when not given here. ${sizeNote}`,
+            }),
+        }, STRICT),
+        t.Object({
+            ...attachmentMetadata,
+            contentPath: t.String({
+                ...id,
+                description: `A regular file on the runline host, read at call time. ${sizeNote}`,
+            }),
+        }, STRICT),
+        t.Object({
+            ...attachmentMetadata,
+            content: t.String({
+                description: `UTF-8 text content, e.g. a generated CSV. ${sizeNote}`,
+            }),
+        }, STRICT),
+    ];
+}
+/**
+ * Bytes given as base64, or as a googleDrive.file.download result, which
+ * also supplies a name and type. `subject` names the input in errors
+ * (`gmail: attachment 0`).
+ */
+export function base64File(value, subject) {
+    const result = typeof value === "string" ? undefined : value;
+    const content = standardBase64(typeof value === "string" ? value : value.contentBase64);
+    if (content === undefined)
+        throw new Error(`${subject} contentBase64 is not valid base64`);
+    return {
+        bytes: Buffer.from(content, "base64"),
+        name: result?.name || undefined,
+        mimeType: result?.mimeType || undefined,
+    };
+}
+/**
+ * An attachment input's bytes. A download result passed as contentBase64
+ * supplies the name and type the input leaves out; a local file is named
+ * for its path; text is text/plain. Oversized bytes, invalid base64 and
+ * unreadable files are refused here, before any request.
+ */
+export async function attachmentFile(input, index, limits) {
+    const subject = `${limits.plugin}: attachment ${index}`;
+    let file;
+    if ("contentBase64" in input) {
+        file = base64File(input.contentBase64, subject);
+    }
+    else if ("contentPath" in input) {
+        file = {
+            bytes: await readLocalFile(input.contentPath, {
+                subject: `${subject} contentPath`,
+                maxBytes: limits.maxBytes,
+                oversize: limits.oversize,
+            }),
+            name: basename(input.contentPath),
+        };
+    }
+    else {
+        file = {
+            bytes: Buffer.from(input.content, "utf8"),
+            mimeType: "text/plain",
+        };
+    }
+    if (file.bytes.length > limits.maxBytes)
+        throw new Error(limits.oversize);
+    return {
+        bytes: file.bytes,
+        name: input.name ?? file.name,
+        mimeType: input.mimeType ?? file.mimeType,
+    };
+}

package/dist/plugins/_shared/microsoftAuth.js

@@ -1,4 +1,4 @@
-import { AuthError, brokerFor, downloadResource, jsonAnswer, requestFailed, } from "runline";
+import { AuthError, brokerFor, downloadResource, jsonAnswer, presignedRequest, responseFailed, } from "runline";
 import { MICROSOFT_GRANT, microsoftCredential, microsoftEndpoint, microsoftUserBase, } from "./microsoftCredentials.js";
 export { microsoftCredential, microsoftDriveBase, } from "./microsoftCredentials.js";
 export function userBase(ctx) {
@@ -7,7 +7,11 @@ export function userBase(ctx) {
 export async function microsoftProbe(ctx, plugin, scopes) {
     return brokerFor(ctx, microsoftCredential(plugin, scopes)).probe();
 }
-export async function graphResponse(ctx, plugin, scopes, method, path, body, contentType) {
+/**
+ * One Graph request under the plugin's credential. `accept` is JSON
+ * unless the caller reads raw bytes, such as an attachment's `$value`.
+ */
+export async function graphResponse(ctx, plugin, scopes, method, path, body, contentType, accept = "application/json") {
     if (!path.startsWith("/") || path.startsWith("//"))
         throw new AuthError("request_not_allowed");
     return brokerFor(ctx, microsoftCredential(plugin, scopes)).request({
@@ -15,12 +19,21 @@ export async function graphResponse(ctx, plugin, scopes, method, path, body, con
         path: path.slice(1),
         method: method,
         headers: {
-            Accept: "application/json",
+            Accept: accept,
             ...(contentType ? { "Content-Type": contentType } : {}),
         },
         body,
     });
 }
+/**
+ * A failed Graph response, by its status and Graph's `error.code`
+ * (`ErrorItemNotFound`, `ErrorAccessDenied`); Graph's message is never read.
+ */
+export function graphFailed(plugin, response) {
+    return responseFailed(plugin, response, (body) => ({
+        code: body?.error?.code,
+    }));
+}
 /**
  * A Graph JSON request that must succeed; its answer is read by
  * `jsonAnswer`. JSON and binary requests share the same destination,
@@ -29,7 +42,7 @@ export async function graphResponse(ctx, plugin, scopes, method, path, body, con
 export async function graphRequest(ctx, plugin, scopes, method, path, body) {
     const res = await graphResponse(ctx, plugin, scopes, method, path, body === undefined ? undefined : JSON.stringify(body), body === undefined ? undefined : "application/json");
     if (!res.ok)
-        throw requestFailed(plugin, res.status);
+        throw await graphFailed(plugin, res);
     return jsonAnswer(res);
 }
 /** Graph-issued signed download URLs carry their own authority, never a bearer header. */
@@ -57,6 +70,22 @@ export async function microsoftDownload(value) {
         fetch: globalThis.fetch,
     });
 }
+/** Where Graph's Outlook attachment upload sessions live, as Microsoft documents them. */
+const OUTLOOK_UPLOAD_ORIGIN = "https://outlook.office.com";
+/**
+ * One request to an Outlook attachment upload session's `uploadUrl`. The
+ * URL carries its own authority, so the request has no bearer token; a
+ * URL on any other origin is refused.
+ */
+export function outlookUpload(uploadUrl, init) {
+    if (typeof uploadUrl !== "string")
+        throw new AuthError("invalid_response");
+    return presignedRequest(uploadUrl, {
+        allowedOrigins: [OUTLOOK_UPLOAD_ORIGIN],
+        fetch: globalThis.fetch,
+        ...init,
+    });
+}
 /**
  * A Microsoft Graph plugin's OAuth declaration: the multi-tenant endpoints,
  * `offline_access` for a refresh token, the grant every Graph plugin

package/dist/plugins/_shared/schemas.js

@@ -0,0 +1,8 @@
+/**
+ * At least one of `fields` must be given: "provide a change", "name a
+ * recipient". Keyed off the field record itself, so the rule cannot drift
+ * from the fields it governs.
+ */
+export function atLeastOne(fields) {
+    return { anyOf: Object.keys(fields).map((key) => ({ required: [key] })) };
+}

package/dist/plugins/agentMail/src/drafts.js

@@ -1,5 +1,6 @@
 import * as t from "typebox";
-import { atLeastOne, attachments, clientId, contentFields, draftFields, id, idList, inboxFields, labelFields, listFields, STRICT, sendFields, strings, timestamp, } from "./schemas.js";
+import { atLeastOne } from "../../_shared/schemas.js";
+import { attachments, clientId, contentFields, draftFields, id, idList, inboxFields, labelFields, listFields, STRICT, sendFields, strings, timestamp, } from "./schemas.js";
 import { attachmentPath, draftPath, inboxPath, request, sendMessage, } from "./shared.js";
 const list = t.Object({ ...inboxFields, ...listFields }, STRICT);
 const draft = t.Object(draftFields, STRICT);

package/dist/plugins/agentMail/src/inboxes.js

@@ -1,5 +1,6 @@
 import * as t from "typebox";
-import { atLeastOne, clientId, id, inboxFields, pageFields, STRICT, } from "./schemas.js";
+import { atLeastOne } from "../../_shared/schemas.js";
+import { clientId, id, inboxFields, pageFields, STRICT } from "./schemas.js";
 import { inboxPath, request } from "./shared.js";
 const metadataValue = t.Union([
     t.String({ maxLength: 256 }),

package/dist/plugins/agentMail/src/messages.js

@@ -1,5 +1,6 @@
 import * as t from "typebox";
-import { atLeastOne, id, inboxFields, labelFields, mailListFields, messageContentFields, messageFields, recipientFields, replyContentFields, STRICT, searchFields, sendFields, strings, } from "./schemas.js";
+import { atLeastOne } from "../../_shared/schemas.js";
+import { id, inboxFields, labelFields, mailListFields, messageContentFields, messageFields, recipientFields, replyContentFields, STRICT, searchFields, sendFields, strings, } from "./schemas.js";
 import { attachmentPath, inboxPath, messagePath, request, sendMessage, } from "./shared.js";
 const list = t.Object({
     ...inboxFields,