@aeolus-fleet/gateway 0.0.0-stage → 0.28.0

package/dist/core/mcp-out/run-party.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-party.js","sourceRoot":"","sources":["../../../src/core/mcp-out/run-party.ts"],"names":[],"mappings":"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"}

package/dist/core/mcp-out/state-party.d.ts

@@ -0,0 +1,39 @@
+import type { FleetId } from '@aeolus-fleet/common';
+import type { FleetRefusal } from '../connection/ports.js';
+import type { PartyStore } from '../parties/ports.js';
+import { type DomainError } from '../shared/errors.js';
+import { type Result } from '../shared/result.js';
+import type { McpServers } from './ports.js';
+import { type CallTiming, type Statement } from './statement.js';
+/** Outbound port: the fleet's `setStatement`, called as a proxy ship's crew. */
+export interface StatementDoor {
+    setStatement(crewToken: string, statement: Statement): Promise<Result<void, FleetRefusal>>;
+}
+/** Outbound port: argo's repeatable marks, by party and tool. */
+export interface ToolMarks {
+    /** The tools of the party argo marked repeatable. */
+    repeatable(fleetId: FleetId, party: string): Promise<ReadonlySet<string>>;
+    mark(fleetId: FleetId, mark: {
+        party: string;
+        tool: string;
+        isRepeatable: boolean;
+    }): Promise<void>;
+}
+export type StateParty = (input: {
+    fleetId: FleetId;
+    name: string;
+}) => Promise<Result<{
+    capabilities: string[];
+}, DomainError<'NO_SUCH_PARTY' | 'NOT_CREWED' | 'SERVER_UNREACHABLE' | 'STATEMENT_REFUSED'>>>;
+/**
+ * Use case: the gateway states what a party's proxy ship offers, as its
+ * crew: the tools its server lists now, with argo's marks. The whole
+ * statement replaces the one before, so a tool the server dropped is gone.
+ */
+export declare function createStateParty(deps: {
+    parties: PartyStore;
+    servers: McpServers;
+    door: StatementDoor;
+    marks: ToolMarks;
+    timing: CallTiming;
+}): StateParty;

package/dist/core/mcp-out/state-party.js

@@ -0,0 +1,30 @@
+import { refuse } from '../shared/errors.js';
+import { ok } from '../shared/result.js';
+import { statementOf } from './statement.js';
+/**
+ * Use case: the gateway states what a party's proxy ship offers, as its
+ * crew: the tools its server lists now, with argo's marks. The whole
+ * statement replaces the one before, so a tool the server dropped is gone.
+ */
+export function createStateParty(deps) {
+    return async ({ fleetId, name }) => {
+        const party = await deps.parties.find(fleetId, name);
+        if (party?.kind !== 'mcpServer') {
+            return refuse('NO_SUCH_PARTY', `No party named ${name}`);
+        }
+        if (party.state !== 'crewed' || party.crewToken === null) {
+            return refuse('NOT_CREWED', `The gateway does not crew the proxy ship of ${name} yet`);
+        }
+        const listed = await deps.servers.listTools({ url: party.url, credential: party.credential });
+        if (!listed.isOk) {
+            return refuse('SERVER_UNREACHABLE', `The MCP server of ${name} could not be listed: ${listed.error.reason}`);
+        }
+        const statement = statementOf({ partyName: name, tools: listed.value, repeatable: await deps.marks.repeatable(fleetId, name), timing: deps.timing });
+        const stated = await deps.door.setStatement(party.crewToken, statement);
+        if (!stated.isOk) {
+            return refuse('STATEMENT_REFUSED', `The fleet refused the statement: ${stated.error.message}`);
+        }
+        return ok({ capabilities: statement.capabilities.map((capability) => capability.name) });
+    };
+}
+//# sourceMappingURL=state-party.js.map

package/dist/core/mcp-out/state-party.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-party.js","sourceRoot":"","sources":["../../../src/core/mcp-out/state-party.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,MAAM,EAAoB,MAAM,qBAAqB,CAAC;AAC/D,OAAO,EAAE,EAAE,EAAe,MAAM,qBAAqB,CAAC;AAEtD,OAAO,EAAE,WAAW,EAAmC,MAAM,gBAAgB,CAAC;AAkB9E;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAA6G;IAC5I,OAAO,KAAK,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE;QACjC,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QACrD,IAAI,KAAK,EAAE,IAAI,KAAK,WAAW,EAAE,CAAC;YAChC,OAAO,MAAM,CAAC,eAAe,EAAE,kBAAkB,IAAI,EAAE,CAAC,CAAC;QAC3D,CAAC;QACD,IAAI,KAAK,CAAC,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,SAAS,KAAK,IAAI,EAAE,CAAC;YACzD,OAAO,MAAM,CAAC,YAAY,EAAE,+CAA+C,IAAI,MAAM,CAAC,CAAC;QACzF,CAAC;QACD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,UAAU,EAAE,KAAK,CAAC,UAAU,EAAE,CAAC,CAAC;QAC9F,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;YACjB,OAAO,MAAM,CAAC,oBAAoB,EAAE,qBAAqB,IAAI,yBAAyB,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;QAC/G,CAAC;QACD,MAAM,SAAS,GAAG,WAAW,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;QACrJ,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;QACxE,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;YACjB,OAAO,MAAM,CAAC,mBAAmB,EAAE,oCAAoC,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QACjG,CAAC;QACD,OAAO,EAAE,CAAC,EAAE,YAAY,EAAE,SAAS,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC3F,CAAC,CAAC;AACJ,CAAC"}

package/dist/core/mcp-out/statement.d.ts

@@ -0,0 +1,36 @@
+import type { OutsideTool, ToolAnnotations } from './ports.js';
+export interface Capability {
+    readonly name: string;
+    readonly title?: string;
+    readonly description?: string;
+    readonly inputSchema: Readonly<Record<string, unknown>>;
+    readonly outputSchema?: Readonly<Record<string, unknown>>;
+    readonly inputModes: readonly string[];
+    readonly outputModes: readonly string[];
+    readonly annotations?: ToolAnnotations;
+    /** How long a caller waits for the answer before it is answered a handle or task (interop 5.3). */
+    readonly waitMs: number;
+    /** How long a call may take before it fails: when the gateway gives up on the server (interop 3.4). */
+    readonly deadlineMs: number;
+    /** argo's mark that a call may be handed again when it died unanswered; the server's hints never set it. */
+    readonly repeatable?: true;
+}
+export interface Statement {
+    readonly summary: string;
+    readonly capabilities: readonly Capability[];
+}
+/** The gateway's own timing for a call to an outside server: how long a caller waits, and when the call fails. */
+export interface CallTiming {
+    readonly waitMs: number;
+    readonly deadlineMs: number;
+}
+/**
+ * The statement of a party's proxy ship. Its summary names the party only:
+ * the server's URL and credential stay in the gateway (NAT both ways).
+ */
+export declare function statementOf(input: {
+    partyName: string;
+    tools: readonly OutsideTool[];
+    repeatable: ReadonlySet<string>;
+    timing: CallTiming;
+}): Statement;

package/dist/core/mcp-out/statement.js

@@ -0,0 +1,34 @@
+/**
+ * A proxy ship's statement (decision 0047), written from its outside MCP
+ * server's `tools/list`: each tool is one capability, with MCP's fields as
+ * the server states them (decision 0048), the content types that call it
+ * and carry its result, argo's repeatable mark (interop 5.2), and the
+ * gateway's own wait and deadline for a call (interop 3.4, 5.3).
+ */
+import { toolInputType, toolResultType } from './content-types.js';
+function capabilityOf(tool, marked) {
+    return {
+        name: tool.name,
+        ...(tool.title === undefined ? {} : { title: tool.title }),
+        ...(tool.description === undefined ? {} : { description: tool.description }),
+        inputSchema: tool.inputSchema,
+        ...(tool.outputSchema === undefined ? {} : { outputSchema: tool.outputSchema }),
+        inputModes: [toolInputType(tool.name)],
+        outputModes: [toolResultType(tool.name)],
+        ...(tool.annotations === undefined ? {} : { annotations: tool.annotations }),
+        ...(marked.isRepeatable ? { repeatable: true } : {}),
+        waitMs: marked.timing.waitMs,
+        deadlineMs: marked.timing.deadlineMs,
+    };
+}
+/**
+ * The statement of a party's proxy ship. Its summary names the party only:
+ * the server's URL and credential stay in the gateway (NAT both ways).
+ */
+export function statementOf(input) {
+    return {
+        summary: `${input.partyName}, an outside MCP server reached through the Aeolus gateway. Each capability is one of its tools: send its input type with the tool arguments as a JSON object, and the reply carries the tool result.`,
+        capabilities: input.tools.map((tool) => capabilityOf(tool, { isRepeatable: input.repeatable.has(tool.name), timing: input.timing })),
+    };
+}
+//# sourceMappingURL=statement.js.map

package/dist/core/mcp-out/statement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"statement.js","sourceRoot":"","sources":["../../../src/core/mcp-out/statement.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAgCnE,SAAS,YAAY,CAAC,IAAiB,EAAE,MAAqD;IAC5F,OAAO;QACL,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,GAAG,CAAC,IAAI,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC;QAC1D,GAAG,CAAC,IAAI,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC;QAC5E,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,GAAG,CAAC,IAAI,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,IAAI,CAAC,YAAY,EAAE,CAAC;QAC/E,UAAU,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACtC,WAAW,EAAE,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACxC,GAAG,CAAC,IAAI,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC;QAC5E,GAAG,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,IAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7D,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM;QAC5B,UAAU,EAAE,MAAM,CAAC,MAAM,CAAC,UAAU;KACrC,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,KAAgH;IAC1I,OAAO;QACL,OAAO,EAAE,GAAG,KAAK,CAAC,SAAS,uMAAuM;QAClO,YAAY,EAAE,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,EAAE,YAAY,EAAE,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;KACrI,CAAC;AACJ,CAAC"}

package/dist/core/oauth/authenticate-access-token.d.ts

@@ -0,0 +1,25 @@
+import type { FleetId } from '@aeolus-fleet/common';
+import type { Clock } from '../shared/clock.js';
+import { type Result } from '../shared/result.js';
+import type { IssuedTokens, OAuthSecrets, TokenHolder } from './ports.js';
+/** Who calls with an access token: the fleet and the client it was issued to, and whom it stands for. */
+export type AccessTokenHolder = {
+    readonly fleetId: FleetId;
+    readonly clientId: string;
+    readonly scope: string | null;
+} & TokenHolder;
+export type AuthenticateAccessToken = (accessToken: string) => Promise<Result<AccessTokenHolder, {
+    kind: 'invalidToken';
+}>>;
+/** Whom a code or a pair stands for, alone. */
+export declare function holderOf(held: TokenHolder): TokenHolder;
+/**
+ * Use case: the gateway knows an MCP client by its access token: active,
+ * not expired, and issued for the gateway's own MCP endpoint (RFC 8707).
+ */
+export declare function createAuthenticateAccessToken(deps: {
+    tokens: IssuedTokens;
+    secrets: OAuthSecrets;
+    clock: Clock;
+    resource: string;
+}): AuthenticateAccessToken;

package/dist/core/oauth/authenticate-access-token.js

@@ -0,0 +1,19 @@
+import { err, ok } from '../shared/result.js';
+/** Whom a code or a pair stands for, alone. */
+export function holderOf(held) {
+    return held.kind === 'party' ? { kind: 'party', party: held.party } : { kind: 'account', grantId: held.grantId };
+}
+/**
+ * Use case: the gateway knows an MCP client by its access token: active,
+ * not expired, and issued for the gateway's own MCP endpoint (RFC 8707).
+ */
+export function createAuthenticateAccessToken(deps) {
+    return async (accessToken) => {
+        const pair = await deps.tokens.findByAccess(deps.secrets.hashOf(accessToken));
+        if (pair?.state !== 'active' || pair.resource !== deps.resource || pair.accessExpiresAt.getTime() <= deps.clock.now().getTime()) {
+            return err({ kind: 'invalidToken' });
+        }
+        return ok({ fleetId: pair.fleetId, clientId: pair.clientId, scope: pair.scope, ...holderOf(pair) });
+    };
+}
+//# sourceMappingURL=authenticate-access-token.js.map

package/dist/core/oauth/authenticate-access-token.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authenticate-access-token.js","sourceRoot":"","sources":["../../../src/core/oauth/authenticate-access-token.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,GAAG,EAAE,EAAE,EAAe,MAAM,qBAAqB,CAAC;AAY3D,+CAA+C;AAC/C,MAAM,UAAU,QAAQ,CAAC,IAAiB;IACxC,OAAO,IAAI,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;AACnH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,6BAA6B,CAAC,IAAqF;IACjI,OAAO,KAAK,EAAE,WAAW,EAAE,EAAE;QAC3B,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC;QAC9E,IAAI,IAAI,EAAE,KAAK,KAAK,QAAQ,IAAI,IAAI,CAAC,QAAQ,KAAK,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,eAAe,CAAC,OAAO,EAAE,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC;YAChI,OAAO,GAAG,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,CAAC,CAAC;QACvC,CAAC;QACD,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,GAAG,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACtG,CAAC,CAAC;AACJ,CAAC"}

package/dist/core/oauth/exchange-token.d.ts

@@ -0,0 +1,32 @@
+import type { Clock } from '../shared/clock.js';
+import { type Result } from '../shared/result.js';
+import type { AuthorizationCodes, IssuedTokens, OAuthClients, OAuthError, OAuthSecrets } from './ports.js';
+/** An access token works one hour; its refresh token 30 days (orchestrator-1 on aeolus-fleet#877, Q13). */
+export declare const ACCESS_TOKEN_LIFETIME_MS: number;
+export declare const REFRESH_TOKEN_LIFETIME_MS: number;
+/** The tokens a client gets. */
+export interface IssuedPair {
+    readonly accessToken: string;
+    readonly refreshToken: string;
+    readonly expiresInSeconds: number;
+    readonly scope: string | null;
+}
+/** A token request's parameters, the client's credentials among them, however it sent them. */
+export type TokenRequest = Readonly<Record<string, string | undefined>>;
+export type ExchangeToken = (request: TokenRequest) => Promise<Result<IssuedPair, OAuthError>>;
+/**
+ * Use case: a client takes its code for tokens, or refreshes them (OAuth
+ * 2.1). A confidential client proves its secret; a public one, or one known
+ * by its metadata document, needs none, as PKCE binds the code to it. A code
+ * is taken once: a second try revokes every token it gave. A refresh token
+ * is taken once too: the pair rotates, and a rotated one coming again
+ * revokes its whole family.
+ */
+export declare function createExchangeToken(deps: {
+    clients: OAuthClients;
+    codes: AuthorizationCodes;
+    tokens: IssuedTokens;
+    secrets: OAuthSecrets;
+    clock: Clock;
+    resource: string;
+}): ExchangeToken;

package/dist/core/oauth/exchange-token.js

@@ -0,0 +1,98 @@
+import { err, ok } from '../shared/result.js';
+import { holderOf } from './authenticate-access-token.js';
+/** An access token works one hour; its refresh token 30 days (orchestrator-1 on aeolus-fleet#877, Q13). */
+export const ACCESS_TOKEN_LIFETIME_MS = 60 * 60_000;
+export const REFRESH_TOKEN_LIFETIME_MS = 30 * 24 * 60 * 60_000;
+const MS_PER_SECOND = 1000;
+function refusal(error, description) {
+    return err({ error, description });
+}
+/**
+ * Use case: a client takes its code for tokens, or refreshes them (OAuth
+ * 2.1). A confidential client proves its secret; a public one, or one known
+ * by its metadata document, needs none, as PKCE binds the code to it. A code
+ * is taken once: a second try revokes every token it gave. A refresh token
+ * is taken once too: the pair rotates, and a rotated one coming again
+ * revokes its whole family.
+ */
+export function createExchangeToken(deps) {
+    /** The client is who it says, as far as it has a secret. */
+    const isAuthenticated = async (request) => {
+        const clientId = request.client_id;
+        if (clientId === undefined) {
+            return false;
+        }
+        const secretHash = (await deps.clients.find(clientId))?.secretHash ?? null;
+        if (secretHash === null) {
+            return request.client_secret === undefined;
+        }
+        return request.client_secret !== undefined && deps.secrets.hashOf(request.client_secret) === secretHash;
+    };
+    const issue = async (from) => {
+        const accessToken = deps.secrets.newSecret();
+        const refreshToken = deps.secrets.newSecret();
+        const now = deps.clock.now().getTime();
+        await deps.tokens.save({
+            ...from,
+            accessHash: deps.secrets.hashOf(accessToken),
+            accessExpiresAt: new Date(now + ACCESS_TOKEN_LIFETIME_MS),
+            refreshHash: deps.secrets.hashOf(refreshToken),
+            refreshExpiresAt: new Date(now + REFRESH_TOKEN_LIFETIME_MS),
+        });
+        return { accessToken, refreshToken, expiresInSeconds: ACCESS_TOKEN_LIFETIME_MS / MS_PER_SECOND, scope: from.scope };
+    };
+    const fromCode = async (request) => {
+        const { code, code_verifier: verifier } = request;
+        if (code === undefined || verifier === undefined) {
+            return refusal('invalid_request', 'A code and its PKCE verifier are required');
+        }
+        if (request.resource !== undefined && request.resource !== deps.resource) {
+            return refusal('invalid_target', `The resource must be ${deps.resource}`);
+        }
+        const taken = await deps.codes.take(deps.secrets.hashOf(code));
+        if (!taken) {
+            return refusal('invalid_grant', 'No such code');
+        }
+        if (taken.wasUsed) {
+            await deps.tokens.revokeIssuedBy(taken.code.codeHash);
+            return refusal('invalid_grant', 'The code was used before; the tokens it gave are revoked');
+        }
+        const issued = taken.code;
+        const isValid = issued.expiresAt.getTime() > deps.clock.now().getTime() &&
+            issued.clientId === request.client_id &&
+            issued.redirectUri === request.redirect_uri &&
+            deps.secrets.challengeOf(verifier) === issued.codeChallenge;
+        if (!isValid) {
+            return refusal('invalid_grant', 'The code is expired, or was issued to another client, redirect URI or verifier');
+        }
+        const { codeHash, fleetId, clientId, resource, scope } = issued;
+        return ok(await issue({ familyId: codeHash, codeHash, fleetId, clientId, resource, scope, ...holderOf(issued) }));
+    };
+    const fromRefreshToken = async (request) => {
+        if (request.refresh_token === undefined) {
+            return refusal('invalid_request', 'A refresh token is required');
+        }
+        const refreshHash = deps.secrets.hashOf(request.refresh_token);
+        const pair = await deps.tokens.findByRefresh(refreshHash);
+        if (!pair || pair.clientId !== request.client_id || pair.refreshExpiresAt.getTime() <= deps.clock.now().getTime() || pair.state === 'revoked') {
+            return refusal('invalid_grant', 'No such refresh token for this client, or it expired');
+        }
+        if (!(await deps.tokens.rotate(refreshHash))) {
+            await deps.tokens.revokeFamily(pair.familyId);
+            return refusal('invalid_grant', 'The refresh token was used before; its tokens are revoked');
+        }
+        const { familyId, codeHash, fleetId, clientId, resource, scope } = pair;
+        return ok(await issue({ familyId, codeHash, fleetId, clientId, resource, scope, ...holderOf(pair) }));
+    };
+    return async (request) => {
+        const grantType = request.grant_type;
+        if (grantType !== 'authorization_code' && grantType !== 'refresh_token') {
+            return refusal('unsupported_grant_type', 'Only authorization_code and refresh_token are served');
+        }
+        if (!(await isAuthenticated(request))) {
+            return refusal('invalid_client', 'The client could not be authenticated');
+        }
+        return grantType === 'authorization_code' ? fromCode(request) : fromRefreshToken(request);
+    };
+}
+//# sourceMappingURL=exchange-token.js.map

package/dist/core/oauth/exchange-token.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exchange-token.js","sourceRoot":"","sources":["../../../src/core/oauth/exchange-token.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,GAAG,EAAE,EAAE,EAAe,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,QAAQ,EAAE,MAAM,gCAAgC,CAAC;AAG1D,2GAA2G;AAC3G,MAAM,CAAC,MAAM,wBAAwB,GAAG,EAAE,GAAG,MAAM,CAAC;AACpD,MAAM,CAAC,MAAM,yBAAyB,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,MAAM,CAAC;AAe/D,MAAM,aAAa,GAAG,IAAI,CAAC;AAE3B,SAAS,OAAO,CAAC,KAAqB,EAAE,WAAmB;IACzD,OAAO,GAAG,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC,CAAC;AACrC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAuI;IACzK,4DAA4D;IAC5D,MAAM,eAAe,GAAG,KAAK,EAAE,OAAqB,EAAoB,EAAE;QACxE,MAAM,QAAQ,GAAG,OAAO,CAAC,SAAS,CAAC;QACnC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,OAAO,KAAK,CAAC;QACf,CAAC;QACD,MAAM,UAAU,GAAG,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,EAAE,UAAU,IAAI,IAAI,CAAC;QAC3E,IAAI,UAAU,KAAK,IAAI,EAAE,CAAC;YACxB,OAAO,OAAO,CAAC,aAAa,KAAK,SAAS,CAAC;QAC7C,CAAC;QACD,OAAO,OAAO,CAAC,aAAa,KAAK,SAAS,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,aAAa,CAAC,KAAK,UAAU,CAAC;IAC1G,CAAC,CAAC;IAEF,MAAM,KAAK,GAAG,KAAK,EAAE,IAA4G,EAAuB,EAAE;QACxJ,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;QAC7C,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;QAC9C,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC;QACvC,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;YACrB,GAAG,IAAI;YACP,UAAU,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,WAAW,CAAC;YAC5C,eAAe,EAAE,IAAI,IAAI,CAAC,GAAG,GAAG,wBAAwB,CAAC;YACzD,WAAW,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,YAAY,CAAC;YAC9C,gBAAgB,EAAE,IAAI,IAAI,CAAC,GAAG,GAAG,yBAAyB,CAAC;SAC5D,CAAC,CAAC;QACH,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,gBAAgB,EAAE,wBAAwB,GAAG,aAAa,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC;IACtH,CAAC,CAAC;IAEF,MAAM,QAAQ,GAAG,KAAK,EAAE,OAAqB,EAA2C,EAAE;QACxF,MAAM,EAAE,IAAI,EAAE,aAAa,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC;QAClD,IAAI,IAAI,KAAK,SAAS,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YACjD,OAAO,OAAO,CAAC,iBAAiB,EAAE,2CAA2C,CAAC,CAAC;QACjF,CAAC;QACD,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS,IAAI,OAAO,CAAC,QAAQ,KAAK,IAAI,CAAC,QAAQ,EAAE,CAAC;YACzE,OAAO,OAAO,CAAC,gBAAgB,EAAE,wBAAwB,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;QAC5E,CAAC;QACD,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;QAC/D,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,OAAO,CAAC,eAAe,EAAE,cAAc,CAAC,CAAC;QAClD,CAAC;QACD,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;YAClB,MAAM,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACtD,OAAO,OAAO,CAAC,eAAe,EAAE,0DAA0D,CAAC,CAAC;QAC9F,CAAC;QACD,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC;QAC1B,MAAM,OAAO,GACX,MAAM,CAAC,SAAS,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE;YACvD,MAAM,CAAC,QAAQ,KAAK,OAAO,CAAC,SAAS;YACrC,MAAM,CAAC,WAAW,KAAK,OAAO,CAAC,YAAY;YAC3C,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,QAAQ,CAAC,KAAK,MAAM,CAAC,aAAa,CAAC;QAC9D,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,OAAO,CAAC,eAAe,EAAE,gFAAgF,CAAC,CAAC;QACpH,CAAC;QACD,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,MAAM,CAAC;QAChE,OAAO,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC;IACpH,CAAC,CAAC;IAEF,MAAM,gBAAgB,GAAG,KAAK,EAAE,OAAqB,EAA2C,EAAE;QAChG,IAAI,OAAO,CAAC,aAAa,KAAK,SAAS,EAAE,CAAC;YACxC,OAAO,OAAO,CAAC,iBAAiB,EAAE,6BAA6B,CAAC,CAAC;QACnE,CAAC;QACD,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;QAC/D,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,WAAW,CAAC,CAAC;QAC1D,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,QAAQ,KAAK,OAAO,CAAC,SAAS,IAAI,IAAI,CAAC,gBAAgB,CAAC,OAAO,EAAE,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YAC9I,OAAO,OAAO,CAAC,eAAe,EAAE,sDAAsD,CAAC,CAAC;QAC1F,CAAC;QACD,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,EAAE,CAAC;YAC7C,MAAM,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAC9C,OAAO,OAAO,CAAC,eAAe,EAAE,2DAA2D,CAAC,CAAC;QAC/F,CAAC;QACD,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,IAAI,CAAC;QACxE,OAAO,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;IACxG,CAAC,CAAC;IAEF,OAAO,KAAK,EAAE,OAAO,EAAE,EAAE;QACvB,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC;QACrC,IAAI,SAAS,KAAK,oBAAoB,IAAI,SAAS,KAAK,eAAe,EAAE,CAAC;YACxE,OAAO,OAAO,CAAC,wBAAwB,EAAE,sDAAsD,CAAC,CAAC;QACnG,CAAC;QACD,IAAI,CAAC,CAAC,MAAM,eAAe,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC;YACtC,OAAO,OAAO,CAAC,gBAAgB,EAAE,uCAAuC,CAAC,CAAC;QAC5E,CAAC;QACD,OAAO,SAAS,KAAK,oBAAoB,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC;IAC5F,CAAC,CAAC;AACJ,CAAC"}

package/dist/core/oauth/issue-code.d.ts

@@ -0,0 +1,23 @@
+import type { FleetId } from '@aeolus-fleet/common';
+import type { Clock } from '../shared/clock.js';
+import type { AuthorizationCodes, OAuthSecrets, TokenHolder } from './ports.js';
+import type { AuthorizationRequest } from './read-authorization.js';
+/** How long a code may be taken for tokens: one minute, within OAuth's ten (RFC 6749, 4.1.2). */
+export declare const CODE_LIFETIME_MS = 60000;
+/** The client's redirect URI with the answer's parameters added, its own query kept. */
+export declare function redirectWith(redirectUri: string, parameters: Record<string, string | null>): string;
+/**
+ * Issues a code bound to the client, its redirect URI, its PKCE challenge,
+ * the resource and whom it stands for, in the fleet; answers where the client
+ * is sent back with it and with the issuer (RFC 9207).
+ */
+export declare function issueCode(deps: {
+    codes: AuthorizationCodes;
+    secrets: OAuthSecrets;
+    clock: Clock;
+    issuer: string;
+}, issued: {
+    fleetId: FleetId;
+    authorization: AuthorizationRequest;
+    holder: TokenHolder;
+}): Promise<string>;

package/dist/core/oauth/issue-code.js

@@ -0,0 +1,34 @@
+/** How long a code may be taken for tokens: one minute, within OAuth's ten (RFC 6749, 4.1.2). */
+export const CODE_LIFETIME_MS = 60_000;
+/** The client's redirect URI with the answer's parameters added, its own query kept. */
+export function redirectWith(redirectUri, parameters) {
+    const url = new URL(redirectUri);
+    for (const [name, value] of Object.entries(parameters)) {
+        if (value !== null) {
+            url.searchParams.append(name, value);
+        }
+    }
+    return url.toString();
+}
+/**
+ * Issues a code bound to the client, its redirect URI, its PKCE challenge,
+ * the resource and whom it stands for, in the fleet; answers where the client
+ * is sent back with it and with the issuer (RFC 9207).
+ */
+export async function issueCode(deps, issued) {
+    const { fleetId, authorization, holder } = issued;
+    const code = deps.secrets.newSecret();
+    await deps.codes.save({
+        codeHash: deps.secrets.hashOf(code),
+        fleetId,
+        clientId: authorization.clientId,
+        redirectUri: authorization.redirectUri,
+        codeChallenge: authorization.codeChallenge,
+        resource: authorization.resource,
+        scope: authorization.scope,
+        expiresAt: new Date(deps.clock.now().getTime() + CODE_LIFETIME_MS),
+        ...holder,
+    });
+    return redirectWith(authorization.redirectUri, { code, state: authorization.state, iss: deps.issuer });
+}
+//# sourceMappingURL=issue-code.js.map

package/dist/core/oauth/issue-code.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"issue-code.js","sourceRoot":"","sources":["../../../src/core/oauth/issue-code.ts"],"names":[],"mappings":"AAMA,iGAAiG;AACjG,MAAM,CAAC,MAAM,gBAAgB,GAAG,MAAM,CAAC;AAEvC,wFAAwF;AACxF,MAAM,UAAU,YAAY,CAAC,WAAmB,EAAE,UAAyC;IACzF,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,WAAW,CAAC,CAAC;IACjC,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;QACvD,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YACnB,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACvC,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC,QAAQ,EAAE,CAAC;AACxB,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,IAAwF,EACxF,MAAsF;IAEtF,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;IAClD,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;IACtC,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;QACpB,QAAQ,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC;QACnC,OAAO;QACP,QAAQ,EAAE,aAAa,CAAC,QAAQ;QAChC,WAAW,EAAE,aAAa,CAAC,WAAW;QACtC,aAAa,EAAE,aAAa,CAAC,aAAa;QAC1C,QAAQ,EAAE,aAAa,CAAC,QAAQ;QAChC,KAAK,EAAE,aAAa,CAAC,KAAK;QAC1B,SAAS,EAAE,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,GAAG,gBAAgB,CAAC;QAClE,GAAG,MAAM;KACV,CAAC,CAAC;IACH,OAAO,YAAY,CAAC,aAAa,CAAC,WAAW,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,aAAa,CAAC,KAAK,EAAE,GAAG,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;AACzG,CAAC"}

package/dist/core/oauth/ports.d.ts

@@ -0,0 +1,105 @@
+/**
+ * The gateway's OAuth 2.1 authorization server for outside MCP clients
+ * (interop 3.1, MCP 2026-07-28 authorization): its clients, the codes it
+ * issues, the tokens it issues, and the secrets behind them.
+ */
+import type { FleetId } from '@aeolus-fleet/common';
+import type { Result } from '../shared/result.js';
+/** A client argo pre-registered for its fleet. A confidential one has a secret, kept only as its hash. */
+export interface OAuthClient {
+    readonly clientId: string;
+    readonly fleetId: FleetId;
+    readonly name: string;
+    readonly redirectUris: readonly string[];
+    readonly secretHash: string | null;
+}
+export interface OAuthClients {
+    find(clientId: string): Promise<OAuthClient | undefined>;
+    save(client: OAuthClient): Promise<void>;
+}
+/** Outbound port: a client's metadata document (CIMD), fetched from its client id URL, as JSON not yet read. */
+export interface ClientMetadataDocuments {
+    fetch(url: string): Promise<Result<unknown, {
+        reason: string;
+    }>>;
+}
+/** A code argo's approval issued: used once, within its minute, by the client and redirect URI it was issued to. */
+/**
+ * Whom a code and the tokens it leads to stand for: a party argo approved,
+ * the proxy ship its client calls the fleet as; or an account a person
+ * signed in as through pagasae, by its grant (decision 0054).
+ */
+export type TokenHolder = {
+    readonly kind: 'party';
+    readonly party: string;
+} | {
+    readonly kind: 'account';
+    readonly grantId: string;
+};
+export type AuthorizationCode = {
+    readonly codeHash: string;
+    readonly fleetId: FleetId;
+    readonly clientId: string;
+    readonly redirectUri: string;
+    /** The PKCE challenge, S256. */
+    readonly codeChallenge: string;
+    readonly resource: string;
+    readonly scope: string | null;
+    readonly expiresAt: Date;
+} & TokenHolder;
+export interface AuthorizationCodes {
+    save(code: AuthorizationCode): Promise<void>;
+    /** Marks the code used, at most once even under a race: the code, and whether it had been used before. */
+    take(codeHash: string): Promise<{
+        code: AuthorizationCode;
+        wasUsed: boolean;
+    } | undefined>;
+}
+/** An access token and its refresh token, issued together; a family is every pair one code led to. */
+export type TokenPair = {
+    readonly familyId: string;
+    readonly codeHash: string;
+    readonly fleetId: FleetId;
+    readonly clientId: string;
+    readonly resource: string;
+    readonly scope: string | null;
+    readonly accessHash: string;
+    readonly accessExpiresAt: Date;
+    readonly refreshHash: string;
+    readonly refreshExpiresAt: Date;
+} & TokenHolder;
+export interface IssuedTokens {
+    /** A new pair, active. */
+    save(pair: TokenPair): Promise<void>;
+    findByAccess(accessHash: string): Promise<(TokenPair & {
+        state: TokenState;
+    }) | undefined>;
+    findByRefresh(refreshHash: string): Promise<(TokenPair & {
+        state: TokenState;
+    }) | undefined>;
+    /** Marks an active pair rotated, at most once even under a race: whether this call did. */
+    rotate(refreshHash: string): Promise<boolean>;
+    revokeFamily(familyId: string): Promise<void>;
+    revokeIssuedBy(codeHash: string): Promise<void>;
+    /** Revokes every pair that stands for the account grant in the fleet: its person signs in again. */
+    revokeGrant(fleetId: FleetId, grantId: string): Promise<void>;
+    /** Revokes every pair that stands for the party in the fleet: its client is refused at its next call. */
+    revokeParty(fleetId: FleetId, party: string): Promise<void>;
+}
+/** active: in use; rotated: its refresh token was traded for a new pair; revoked: refused for good. */
+export type TokenState = 'active' | 'rotated' | 'revoked';
+/** Outbound port: the secrets the server issues, how it keeps them, and PKCE's S256. */
+export interface OAuthSecrets {
+    /** A new random secret, safe in a URL. */
+    newSecret(): string;
+    /** The hash a secret is kept as, and looked up by. */
+    hashOf(secret: string): string;
+    /** PKCE S256: BASE64URL(SHA256(verifier)). */
+    challengeOf(verifier: string): string;
+}
+/** OAuth's error codes the gateway answers (RFC 6749, RFC 8707). */
+export type OAuthErrorCode = 'invalid_request' | 'invalid_client' | 'invalid_grant' | 'unsupported_grant_type' | 'unsupported_response_type' | 'invalid_target' | 'access_denied';
+export interface OAuthError {
+    readonly error: OAuthErrorCode;
+    readonly description: string;
+}

package/dist/core/oauth/ports.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ports.js.map

package/dist/core/oauth/ports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ports.js","sourceRoot":"","sources":["../../../src/core/oauth/ports.ts"],"names":[],"mappings":""}

package/dist/core/oauth/read-authorization.d.ts

@@ -0,0 +1,43 @@
+import type { FleetId } from '@aeolus-fleet/common';
+import { type Result } from '../shared/result.js';
+import type { ClientMetadataDocuments, OAuthClients, OAuthErrorCode } from './ports.js';
+/** An authorization request the gateway read and found valid, for argo to approve or deny. */
+export interface AuthorizationRequest {
+    readonly clientId: string;
+    readonly clientName: string;
+    /** The fleet a pre-registered client belongs to; null for a client known by its metadata document. */
+    readonly clientFleetId: FleetId | null;
+    readonly redirectUri: string;
+    readonly codeChallenge: string;
+    readonly resource: string;
+    readonly scope: string | null;
+    readonly state: string | null;
+}
+/**
+ * Why a request is refused:
+ * - invalidClient: the client or its redirect URI is not known, so the page says so and sends nobody anywhere (RFC 6749, 4.1.2.1);
+ * - redirect: the client is known, so it is sent back to its redirect URI with the error.
+ */
+export type AuthorizationRefusal = {
+    readonly kind: 'invalidClient';
+    readonly message: string;
+} | {
+    readonly kind: 'redirect';
+    readonly redirectUri: string;
+    readonly error: OAuthErrorCode;
+    readonly description: string;
+    readonly state: string | null;
+};
+export type ReadAuthorization = (request: Readonly<Record<string, string | undefined>>) => Promise<Result<AuthorizationRequest, AuthorizationRefusal>>;
+/**
+ * Use case: the gateway reads an authorization request from an MCP client
+ * (OAuth 2.1 with PKCE, MCP 2026-07-28). The client is pre-registered, or
+ * known by its metadata document (CIMD), fetched from its client id. Only
+ * the S256 challenge is taken, and the resource must be the gateway's MCP
+ * endpoint (RFC 8707), so a token is bound to it.
+ */
+export declare function createReadAuthorization(deps: {
+    clients: OAuthClients;
+    documents: ClientMetadataDocuments;
+    resource: string;
+}): ReadAuthorization;