runline 0.35.0 → 0.36.0

package/dist/auth/errors.d.ts

@@ -8,9 +8,9 @@ declare const messages: {
     readonly binding_changed: "Credential binding identity changed";
     readonly unsupported_operation: "Authentication operation is not supported";
     readonly invalid_response: "Invalid provider response";
-    readonly request_failed: "OAuth token request failed; provider outcome may be unknown";
-    readonly provider_rejected: "OAuth provider rejected the token request";
-    readonly reconnect_required: "OAuth grant is invalid; reconnect the account";
+    readonly request_failed: "Token request failed; provider outcome may be unknown";
+    readonly provider_rejected: "Provider rejected the token request";
+    readonly reconnect_required: "Credential is no longer valid; reconnect the account";
 };
 export type AuthErrorCode = keyof typeof messages;
 /** Safe to serialize. No raw response, endpoint URL, credential, or nested cause. */

package/dist/auth/errors.js

@@ -8,9 +8,9 @@ const messages = {
     binding_changed: "Credential binding identity changed",
     unsupported_operation: "Authentication operation is not supported",
     invalid_response: "Invalid provider response",
-    request_failed: "OAuth token request failed; provider outcome may be unknown",
-    provider_rejected: "OAuth provider rejected the token request",
-    reconnect_required: "OAuth grant is invalid; reconnect the account",
+    request_failed: "Token request failed; provider outcome may be unknown",
+    provider_rejected: "Provider rejected the token request",
+    reconnect_required: "Credential is no longer valid; reconnect the account",
 };
 /** Safe to serialize. No raw response, endpoint URL, credential, or nested cause. */
 export class AuthError extends Error {

package/dist/credentials/aws-plugin.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The plugin side of AWS: one declaration for an AWS connection — an
+ * access key, or a role it assumes — and the request paths of the AWS
+ * protocols, all signed through the declared credential.
+ */
+import type { ActionContext } from "../plugin/types.js";
+import type { CredentialDeclaration, CredentialProbe, CredentialTarget, HttpMethod } from "./types.js";
+/**
+ * An AWS endpoint as a declared target: the service's regional HTTPS
+ * endpoint, signed for that service and region. `X-Amz-Target`, which
+ * names the operation of a JSON-protocol call, is always allowed.
+ */
+export declare function awsTarget(service: string, region: string, options?: {
+    methods?: HttpMethod[];
+    allowedHeaders?: string[];
+    timeoutMs?: number;
+    maxResponseBytes?: number;
+}): CredentialTarget;
+export interface AwsCredentialSpec {
+    /** Credential type id; one per provider family, shared by its plugins. */
+    id: string;
+    /** The endpoints the plugin calls (`awsTarget`), from public config. */
+    targets: (config: Readonly<Record<string, unknown>>) => Record<string, CredentialTarget>;
+    probe?: CredentialProbe;
+}
+/**
+ * An AWS connection's declaration. The access key — `accessKeyId`,
+ * `secretAccessKey`, and a session's `sessionToken` — is the secret; the
+ * rest is public config:
+ *
+ * - `roleArn` selects `assumeRole`: the key only assumes the role, and
+ *   requests sign with its sessions, renewed before they expire. Without
+ *   it, `accessKey` signs with the key itself.
+ * - `roleSessionName` (default `runline`), `roleExternalId` and
+ *   `roleDurationSeconds` shape each session request.
+ * - `stsRegion`, else `region`, else `us-east-1`, is where sessions are
+ *   requested.
+ */
+export declare function awsCredential(spec: AwsCredentialSpec): CredentialDeclaration;
+/**
+ * A failed AWS response by its status and the AWS error code it names
+ * (`AccessDeniedException`, `InvalidInstanceId.NotFound`). The message
+ * AWS sends with it, which can quote request data, never reaches the
+ * error. The status and code ride on the error for callers that branch.
+ */
+export declare function awsFailed(plugin: string, response: Response): Promise<Error & {
+    status: number;
+    code?: string;
+}>;
+/**
+ * One call of an AWS JSON-protocol service (SSM, CloudWatch Logs,
+ * Secrets Manager, CloudWatch): `operation` is the full
+ * `X-Amz-Target`, e.g. `AmazonSSM.SendCommand`; `version` is the
+ * service's JSON protocol version.
+ */
+export declare function awsJson<T = unknown>(ctx: ActionContext, declaration: CredentialDeclaration, plugin: string, call: {
+    target: string;
+    operation: string;
+    version: "1.0" | "1.1";
+    input?: unknown;
+}): Promise<T>;
+/**
+ * One call of an AWS Query-protocol service (EC2, STS): the action's
+ * parameters as the API names them, lists already numbered
+ * (`Filter.1.Name`). Answers the `<Action>Response` element as data;
+ * `awsList` reads its lists.
+ */
+export declare function awsQuery(ctx: ActionContext, declaration: CredentialDeclaration, plugin: string, call: {
+    target: string;
+    action: string;
+    version: string;
+    params?: Record<string, string | number | boolean | undefined>;
+}): Promise<Record<string, unknown>>;
+/**
+ * The entries of an AWS XML list: EC2's `<item>` and the query
+ * services' `<member>` elements, one or many, and none for an empty or
+ * absent list.
+ */
+export declare function awsList(value: unknown): unknown[];

package/dist/credentials/aws-plugin.js

@@ -0,0 +1,179 @@
+/**
+ * The plugin side of AWS: one declaration for an AWS connection — an
+ * access key, or a role it assumes — and the request paths of the AWS
+ * protocols, all signed through the declared credential.
+ */
+import * as t from "typebox";
+import { AuthError } from "../auth/errors.js";
+import { awsEndpoint, awsErrorCode, awsRole, parseAwsXml } from "./aws.js";
+import { credentialRequest, errorIdentifier, failureMessage, jsonAnswer, } from "./plugin.js";
+import { AwsAccessKeySchema, AwsSessionSchema } from "./registry.js";
+const STRICT = { additionalProperties: false };
+/**
+ * An AWS endpoint as a declared target: the service's regional HTTPS
+ * endpoint, signed for that service and region. `X-Amz-Target`, which
+ * names the operation of a JSON-protocol call, is always allowed.
+ */
+export function awsTarget(service, region, options = {}) {
+    // The endpoint refuses a malformed service or region, so the scope is sound.
+    return {
+        baseUrl: awsEndpoint(service, region),
+        methods: options.methods ?? ["GET", "POST"],
+        allowedHeaders: ["X-Amz-Target", ...(options.allowedHeaders ?? [])],
+        aws: { service, region },
+        ...(options.timeoutMs !== undefined
+            ? { timeoutMs: options.timeoutMs }
+            : {}),
+        ...(options.maxResponseBytes !== undefined
+            ? { maxResponseBytes: options.maxResponseBytes }
+            : {}),
+    };
+}
+/** A whole number from config, which a CLI or environment gives as a string. */
+function configInteger(value) {
+    if (value === undefined || value === null || value === "")
+        return undefined;
+    const number = typeof value === "string" ? Number(value) : value;
+    if (typeof number !== "number" || !Number.isInteger(number))
+        throw new AuthError("invalid_credentials");
+    return number;
+}
+function configString(value) {
+    if (value === undefined || value === null || value === "")
+        return undefined;
+    if (typeof value !== "string")
+        throw new AuthError("invalid_credentials");
+    return value;
+}
+/**
+ * An AWS connection's declaration. The access key — `accessKeyId`,
+ * `secretAccessKey`, and a session's `sessionToken` — is the secret; the
+ * rest is public config:
+ *
+ * - `roleArn` selects `assumeRole`: the key only assumes the role, and
+ *   requests sign with its sessions, renewed before they expire. Without
+ *   it, `accessKey` signs with the key itself.
+ * - `roleSessionName` (default `runline`), `roleExternalId` and
+ *   `roleDurationSeconds` shape each session request.
+ * - `stsRegion`, else `region`, else `us-east-1`, is where sessions are
+ *   requested.
+ */
+export function awsCredential(spec) {
+    const key = { credential: AwsAccessKeySchema };
+    const localSecret = {
+        accessKeyId: { field: "accessKeyId" },
+        secretAccessKey: { field: "secretAccessKey" },
+        sessionToken: { field: "sessionToken" },
+    };
+    return (config) => {
+        const targets = spec.targets(config);
+        const probe = spec.probe ? { probe: spec.probe } : {};
+        const roleArn = configString(config.roleArn);
+        const externalId = configString(config.roleExternalId);
+        const durationSeconds = configInteger(config.roleDurationSeconds);
+        return {
+            type: {
+                id: spec.id,
+                methods: {
+                    accessKey: {
+                        schema: t.Object(key, STRICT),
+                        authentication: { kind: "awsSigV4", field: "credential" },
+                        targets,
+                        ...probe,
+                    },
+                    assumeRole: {
+                        schema: t.Object({ ...key, session: t.Optional(AwsSessionSchema) }, STRICT),
+                        authentication: {
+                            kind: "awsSigV4",
+                            field: "credential",
+                            assumeRole: { sessionField: "session" },
+                        },
+                        targets,
+                        ...probe,
+                    },
+                },
+            },
+            localSecret,
+            ...(roleArn === undefined
+                ? { method: "accessKey" }
+                : {
+                    method: "assumeRole",
+                    awsRole: awsRole({
+                        roleArn,
+                        sessionName: configString(config.roleSessionName) ?? "runline",
+                        ...(externalId === undefined ? {} : { externalId }),
+                        ...(durationSeconds === undefined ? {} : { durationSeconds }),
+                        region: configString(config.stsRegion) ??
+                            configString(config.region) ??
+                            "us-east-1",
+                    }),
+                }),
+        };
+    };
+}
+/**
+ * A failed AWS response by its status and the AWS error code it names
+ * (`AccessDeniedException`, `InvalidInstanceId.NotFound`). The message
+ * AWS sends with it, which can quote request data, never reaches the
+ * error. The status and code ride on the error for callers that branch.
+ */
+export async function awsFailed(plugin, response) {
+    const code = errorIdentifier(awsErrorCode(await response.text()));
+    return Object.assign(new Error(failureMessage(plugin, response.status, { code })), { status: response.status, ...(code ? { code } : {}) });
+}
+/**
+ * One call of an AWS JSON-protocol service (SSM, CloudWatch Logs,
+ * Secrets Manager, CloudWatch): `operation` is the full
+ * `X-Amz-Target`, e.g. `AmazonSSM.SendCommand`; `version` is the
+ * service's JSON protocol version.
+ */
+export async function awsJson(ctx, declaration, plugin, call) {
+    const response = await credentialRequest(ctx, declaration, {
+        target: call.target,
+        path: "",
+        method: "POST",
+        headers: {
+            "Content-Type": `application/x-amz-json-${call.version}`,
+            "X-Amz-Target": call.operation,
+        },
+        body: JSON.stringify(call.input ?? {}),
+    });
+    if (!response.ok)
+        throw await awsFailed(plugin, response);
+    return jsonAnswer(response);
+}
+/**
+ * One call of an AWS Query-protocol service (EC2, STS): the action's
+ * parameters as the API names them, lists already numbered
+ * (`Filter.1.Name`). Answers the `<Action>Response` element as data;
+ * `awsList` reads its lists.
+ */
+export async function awsQuery(ctx, declaration, plugin, call) {
+    const response = await credentialRequest(ctx, declaration, {
+        target: call.target,
+        path: "",
+        method: "POST",
+        headers: { Accept: "text/xml" },
+        form: { Action: call.action, Version: call.version, ...call.params },
+    });
+    if (!response.ok)
+        throw await awsFailed(plugin, response);
+    const answer = parseAwsXml(await response.text())[`${call.action}Response`];
+    if (!answer || typeof answer !== "object")
+        throw new AuthError("invalid_response");
+    return answer;
+}
+/**
+ * The entries of an AWS XML list: EC2's `<item>` and the query
+ * services' `<member>` elements, one or many, and none for an empty or
+ * absent list.
+ */
+export function awsList(value) {
+    if (!value || typeof value !== "object")
+        return [];
+    const holder = value;
+    const entries = holder.item ?? holder.member;
+    if (entries === undefined || entries === "")
+        return [];
+    return Array.isArray(entries) ? entries : [entries];
+}

package/dist/credentials/aws.d.ts

@@ -0,0 +1,41 @@
+import type { AwsAccessKey, AwsRole, AwsSession } from "./types.js";
+/** A region from public config; anything else would sign for the wrong place. */
+export declare function awsRegion(value: unknown): string;
+/** Whether a target's signing scope names a well-formed service and region. */
+export declare function isAwsScope(value: unknown): boolean;
+/**
+ * The regional HTTPS endpoint of `service`: `https://<service>.<region>.
+ * amazonaws.com/`, or `.amazonaws.com.cn` in the China partition.
+ */
+export declare function awsEndpoint(service: string, region: string): string;
+/**
+ * An access key that can sign: an ID and a session token that go into
+ * headers as they are (`secret`), and a secret that only keys the
+ * signature. Anything else is refused before any request.
+ */
+export declare function awsAccessKey(value: unknown): AwsAccessKey;
+/** A role as STS accepts it; anything else is refused before any request. */
+export declare function awsRole(role: AwsRole): AwsRole;
+/**
+ * An AWS XML answer as plain data. Element text is a string; lists are
+ * `item` or `member` entries. AWS sends no document type, and one that
+ * declares entities could expand without bound, so a DOCTYPE is refused.
+ */
+export declare function parseAwsXml(text: string): Record<string, unknown>;
+/**
+ * An AWS error's code, from any of its envelopes: a JSON `__type`
+ * (`com.amazonaws.ssm#InvalidInstanceId` → `InvalidInstanceId`) or `code`,
+ * a query `ErrorResponse`, or EC2's `Response.Errors`. Undefined when the
+ * body names none.
+ */
+export declare function awsErrorCode(text: string): string | undefined;
+export interface AssumeRoleOptions {
+    fetch: typeof globalThis.fetch;
+    timeoutMs: number;
+}
+/**
+ * A new session for `role`, requested from STS with `key`. A refused
+ * key is reconnect_required; any other refusal (no permission to assume
+ * the role, a trust policy mismatch) is provider_rejected.
+ */
+export declare function assumeAwsRole(key: AwsAccessKey, role: AwsRole, options: AssumeRoleOptions): Promise<Omit<AwsSession, "revision">>;

package/dist/credentials/aws.js

@@ -0,0 +1,213 @@
+import { XMLParser } from "fast-xml-parser";
+import { AuthError } from "../auth/errors.js";
+import { sendResource } from "./http.js";
+import { secret } from "./policy.js";
+import { signSigV4 } from "./sigv4.js";
+/**
+ * AWS endpoints, roles and responses: what SigV4 methods sign for, and
+ * how a role session is issued. The signature itself is sigv4.ts.
+ */
+/** A region code: `us-east-1`, `eu-central-2`, `us-gov-west-1`, `cn-north-1`. */
+const REGION = /^[a-z]{2}(?:-[a-z]+)+-\d{1,2}$/;
+/** A service's endpoint prefix: `ec2`, `ssm`, `logs`, `monitoring`. */
+const SERVICE = /^[a-z0-9][a-z0-9-]{0,62}$/;
+/** A region from public config; anything else would sign for the wrong place. */
+export function awsRegion(value) {
+    if (typeof value !== "string" || !REGION.test(value))
+        throw new AuthError("invalid_credentials");
+    return value;
+}
+/** Whether a target's signing scope names a well-formed service and region. */
+export function isAwsScope(value) {
+    const scope = value;
+    return (!!scope &&
+        typeof scope.service === "string" &&
+        SERVICE.test(scope.service) &&
+        typeof scope.region === "string" &&
+        REGION.test(scope.region));
+}
+/**
+ * The regional HTTPS endpoint of `service`: `https://<service>.<region>.
+ * amazonaws.com/`, or `.amazonaws.com.cn` in the China partition.
+ */
+export function awsEndpoint(service, region) {
+    if (!SERVICE.test(service))
+        throw new AuthError("invalid_definition");
+    const domain = awsRegion(region).startsWith("cn-")
+        ? "amazonaws.com.cn"
+        : "amazonaws.com";
+    return `https://${service}.${region}.${domain}/`;
+}
+/**
+ * An access key that can sign: an ID and a session token that go into
+ * headers as they are (`secret`), and a secret that only keys the
+ * signature. Anything else is refused before any request.
+ */
+export function awsAccessKey(value) {
+    const key = value;
+    if (typeof key?.secretAccessKey !== "string" || !key.secretAccessKey)
+        throw new AuthError("invalid_credentials");
+    return {
+        accessKeyId: secret(key.accessKeyId),
+        secretAccessKey: key.secretAccessKey,
+        ...(key.sessionToken === undefined
+            ? {}
+            : { sessionToken: secret(key.sessionToken) }),
+    };
+}
+/** `arn:<partition>:iam::<account>:role/<path/name>`, as IAM allows it. */
+const ROLE_ARN = /^arn:aws(?:-[a-z]+)*:iam::\d{12}:role\/[\w+=,.@/-]{1,512}$/;
+const SESSION_NAME = /^[\w+=,.@-]{2,64}$/;
+const EXTERNAL_ID = /^[\w+=,.@:/-]{2,1224}$/;
+/** A role as STS accepts it; anything else is refused before any request. */
+export function awsRole(role) {
+    if (!ROLE_ARN.test(role.roleArn) ||
+        !SESSION_NAME.test(role.sessionName) ||
+        (role.externalId !== undefined && !EXTERNAL_ID.test(role.externalId)) ||
+        (role.durationSeconds !== undefined &&
+            (!Number.isInteger(role.durationSeconds) ||
+                role.durationSeconds < 900 ||
+                role.durationSeconds > 43_200)))
+        throw new AuthError("invalid_credentials");
+    return { ...role, region: awsRegion(role.region) };
+}
+const xml = new XMLParser({
+    ignoreAttributes: true,
+    ignoreDeclaration: true,
+    // Values stay strings: an account ID or a volume size is not ours to coerce.
+    parseTagValue: false,
+    trimValues: true,
+    processEntities: true,
+    htmlEntities: false,
+});
+/**
+ * An AWS XML answer as plain data. Element text is a string; lists are
+ * `item` or `member` entries. AWS sends no document type, and one that
+ * declares entities could expand without bound, so a DOCTYPE is refused.
+ */
+export function parseAwsXml(text) {
+    if (/<!DOCTYPE/i.test(text))
+        throw new AuthError("invalid_response");
+    try {
+        const parsed = xml.parse(text, true);
+        if (!parsed || typeof parsed !== "object")
+            throw new Error();
+        return parsed;
+    }
+    catch {
+        throw new AuthError("invalid_response");
+    }
+}
+/**
+ * An AWS error's code, from any of its envelopes: a JSON `__type`
+ * (`com.amazonaws.ssm#InvalidInstanceId` → `InvalidInstanceId`) or `code`,
+ * a query `ErrorResponse`, or EC2's `Response.Errors`. Undefined when the
+ * body names none.
+ */
+export function awsErrorCode(text) {
+    const trimmed = text.trim();
+    if (trimmed.startsWith("{")) {
+        try {
+            const body = JSON.parse(trimmed);
+            const code = body.__type ?? body.code ?? body.Code;
+            return typeof code === "string" ? code.split("#").pop() : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (!trimmed.startsWith("<"))
+        return undefined;
+    try {
+        const body = parseAwsXml(trimmed);
+        const envelope = (body.ErrorResponse ?? body.Response);
+        const error = (envelope?.Error ??
+            envelope?.Errors?.Error);
+        const first = Array.isArray(error) ? error[0] : error;
+        return typeof first?.Code === "string" ? first.Code : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** STS codes that mean the signing key itself is unusable: a reconnect, not a retry. */
+const REJECTED_KEY = new Set([
+    "InvalidClientTokenId",
+    "SignatureDoesNotMatch",
+    "ExpiredToken",
+    "InvalidAccessKeyId",
+    "UnrecognizedClientException",
+]);
+/**
+ * A new session for `role`, requested from STS with `key`. A refused
+ * key is reconnect_required; any other refusal (no permission to assume
+ * the role, a trust policy mismatch) is provider_rejected.
+ */
+export async function assumeAwsRole(key, role, options) {
+    const signing = awsAccessKey(key);
+    const valid = awsRole(role);
+    const endpoint = new URL(awsEndpoint("sts", valid.region));
+    const body = Buffer.from(new URLSearchParams({
+        Action: "AssumeRole",
+        Version: "2011-06-15",
+        RoleArn: valid.roleArn,
+        RoleSessionName: valid.sessionName,
+        ...(valid.externalId === undefined
+            ? {}
+            : { ExternalId: valid.externalId }),
+        ...(valid.durationSeconds === undefined
+            ? {}
+            : { DurationSeconds: String(valid.durationSeconds) }),
+    }).toString());
+    const contentType = "application/x-www-form-urlencoded; charset=utf-8";
+    const now = Date.now();
+    const signed = signSigV4({
+        method: "POST",
+        host: endpoint.host,
+        path: endpoint.pathname,
+        query: [],
+        headers: [["content-type", contentType]],
+        body,
+    }, signing, { service: "sts", region: valid.region }, new Date(now));
+    let response;
+    try {
+        response = await sendResource(endpoint.toString(), "POST", new Headers({ "content-type": contentType, ...signed }), body, {
+            fetch: options.fetch,
+            timeoutMs: options.timeoutMs,
+            maxResponseBytes: 64 * 1024,
+        });
+    }
+    catch {
+        throw new AuthError("request_failed");
+    }
+    const text = await response.text();
+    if (!response.ok) {
+        const code = awsErrorCode(text);
+        throw new AuthError(code && REJECTED_KEY.has(code)
+            ? "reconnect_required"
+            : "provider_rejected", response.status);
+    }
+    const result = parseAwsXml(text).AssumeRoleResponse?.AssumeRoleResult?.Credentials;
+    const expiresAt = Date.parse(String(result?.Expiration));
+    if (typeof result?.SessionToken !== "string" ||
+        !Number.isSafeInteger(expiresAt) ||
+        expiresAt <= now)
+        throw new AuthError("invalid_response");
+    let session;
+    try {
+        session = awsAccessKey({
+            accessKeyId: result.AccessKeyId,
+            secretAccessKey: result.SecretAccessKey,
+            sessionToken: result.SessionToken,
+        });
+    }
+    catch {
+        throw new AuthError("invalid_response");
+    }
+    return {
+        accessKeyId: session.accessKeyId,
+        secretAccessKey: session.secretAccessKey,
+        sessionToken: result.SessionToken,
+        expiresAt,
+    };
+}

package/dist/credentials/broker.d.ts

@@ -0,0 +1,11 @@
+import type { ActionContext } from "../plugin/types.js";
+import { type CredentialBroker } from "./transport.js";
+import type { CredentialDeclaration } from "./types.js";
+/**
+ * Where one action call's authenticated requests go: the host's broker
+ * when it supplies one — the credentials then live with the host, and no
+ * local signer is built — else this process signs with its own
+ * connection, from the plugin's declaration. Plugin-side: the host-side
+ * `credentialBroker` option is what supplies `ctx.credentials`.
+ */
+export declare function brokerFor(ctx: ActionContext, declaration: CredentialDeclaration): CredentialBroker;