@aeolus-fleet/gateway 0.33.0 → 0.34.0

package/dist/core/party-grants/party-grant.d.ts

@@ -0,0 +1,50 @@
+import type { FleetId, ShipId } from '@aeolus-fleet/common';
+/** The outside account a grant names, as the outside service's OpenID Connect ID token stated it; none of it where the server gave no ID token. */
+export interface OutsideAccount {
+    /** The `sub` the outside issuer named the account by: no two persons' grants of a party name the same one (Q13). */
+    readonly subject: string | null;
+    /** The account as a person reads it, its email or name, when the ID token named one. */
+    readonly name: string | null;
+}
+/** A grant the authorization server would no longer refresh (Q5): when, and why as the server said it. */
+export interface GrantLost {
+    readonly at: Date;
+    readonly why: string;
+}
+/**
+ * One person's sign-in to one party (decision 0067): the outside account it
+ * names and its access and refresh tokens, kept by the gateway alone, under
+ * the party's client. A person holds one grant per party; a new sign-in
+ * replaces it.
+ */
+export interface PartyGrant {
+    readonly fleetId: FleetId;
+    readonly party: string;
+    /** The person: their person ship, which owns itself, and the ships it owns call under this grant. */
+    readonly personShipId: ShipId;
+    readonly accountId: string;
+    readonly outsideAccount: OutsideAccount;
+    readonly accessToken: string;
+    /** None when the authorization server issued none: the grant then ends with its access token. */
+    readonly refreshToken: string | null;
+    /** None when the authorization server did not say when the access token ends. */
+    readonly accessTokenEndsAt: Date | null;
+    readonly signedInAt: Date;
+    /** When it was last refreshed; none until its first refresh. */
+    readonly refreshedAt: Date | null;
+    readonly lastUsedAt: Date | null;
+    /** None while the grant holds; a lost grant serves no call until the person signs in again in its place. */
+    readonly lost: GrantLost | null;
+}
+/** Whether the grant's access token may still be sent: the grant not lost, and the token's end not reached, or never stated. */
+export declare function isUsable(grant: PartyGrant, now: Date): boolean;
+/** How long before its access token ends a grant is refreshed ahead (Q7): longer than the schedule's round, so the schedule finds it first. */
+export declare const REFRESH_AHEAD_MS: number;
+/** Whether the grant's access token ends within the time a grant is refreshed ahead of, or has ended. */
+export declare function isNearItsEnd(grant: PartyGrant, now: Date): boolean;
+/** How long a grant goes unrefreshed before the schedule refreshes it while idle (Q7, L20): its refresh token used often enough that no idle policy ends it. */
+export declare const IDLE_REFRESH_MS: number;
+/** Whether the schedule refreshes the grant now (Q7): not lost, holding a refresh token, and near its access token's end or unrefreshed since its sign-in or last refresh for longer than the idle time. */
+export declare function isDueForRefresh(grant: PartyGrant, now: Date): boolean;
+/** When an access token issued now ends, from the seconds the authorization server said it lasts; none where it said nothing. */
+export declare function accessTokenEndsAtOf(now: Date, expiresInSeconds: number | null): Date | null;

package/dist/core/party-grants/party-grant.js

@@ -0,0 +1,26 @@
+/** Whether the grant's access token may still be sent: the grant not lost, and the token's end not reached, or never stated. */
+export function isUsable(grant, now) {
+    return grant.lost === null && (grant.accessTokenEndsAt === null || grant.accessTokenEndsAt.getTime() > now.getTime());
+}
+/** How long before its access token ends a grant is refreshed ahead (Q7): longer than the schedule's round, so the schedule finds it first. */
+export const REFRESH_AHEAD_MS = 10 * 60 * 1000;
+/** Whether the grant's access token ends within the time a grant is refreshed ahead of, or has ended. */
+export function isNearItsEnd(grant, now) {
+    return grant.accessTokenEndsAt !== null && grant.accessTokenEndsAt.getTime() - now.getTime() <= REFRESH_AHEAD_MS;
+}
+/** How long a grant goes unrefreshed before the schedule refreshes it while idle (Q7, L20): its refresh token used often enough that no idle policy ends it. */
+export const IDLE_REFRESH_MS = 24 * 60 * 60 * 1000;
+/** Whether the schedule refreshes the grant now (Q7): not lost, holding a refresh token, and near its access token's end or unrefreshed since its sign-in or last refresh for longer than the idle time. */
+export function isDueForRefresh(grant, now) {
+    if (grant.lost !== null || grant.refreshToken === null) {
+        return false;
+    }
+    const refreshedLast = grant.refreshedAt ?? grant.signedInAt;
+    return isNearItsEnd(grant, now) || now.getTime() - refreshedLast.getTime() > IDLE_REFRESH_MS;
+}
+const MS_PER_SECOND = 1000;
+/** When an access token issued now ends, from the seconds the authorization server said it lasts; none where it said nothing. */
+export function accessTokenEndsAtOf(now, expiresInSeconds) {
+    return expiresInSeconds === null ? null : new Date(now.getTime() + expiresInSeconds * MS_PER_SECOND);
+}
+//# sourceMappingURL=party-grant.js.map

package/dist/core/party-grants/party-grant.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"party-grant.js","sourceRoot":"","sources":["../../../src/core/party-grants/party-grant.ts"],"names":[],"mappings":"AA0CA,gIAAgI;AAChI,MAAM,UAAU,QAAQ,CAAC,KAAiB,EAAE,GAAS;IACnD,OAAO,KAAK,CAAC,IAAI,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,iBAAiB,KAAK,IAAI,IAAI,KAAK,CAAC,iBAAiB,CAAC,OAAO,EAAE,GAAG,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;AACxH,CAAC;AAED,+IAA+I;AAC/I,MAAM,CAAC,MAAM,gBAAgB,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAE/C,yGAAyG;AACzG,MAAM,UAAU,YAAY,CAAC,KAAiB,EAAE,GAAS;IACvD,OAAO,KAAK,CAAC,iBAAiB,KAAK,IAAI,IAAI,KAAK,CAAC,iBAAiB,CAAC,OAAO,EAAE,GAAG,GAAG,CAAC,OAAO,EAAE,IAAI,gBAAgB,CAAC;AACnH,CAAC;AAED,gKAAgK;AAChK,MAAM,CAAC,MAAM,eAAe,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAEnD,4MAA4M;AAC5M,MAAM,UAAU,eAAe,CAAC,KAAiB,EAAE,GAAS;IAC1D,IAAI,KAAK,CAAC,IAAI,KAAK,IAAI,IAAI,KAAK,CAAC,YAAY,KAAK,IAAI,EAAE,CAAC;QACvD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,aAAa,GAAG,KAAK,CAAC,WAAW,IAAI,KAAK,CAAC,UAAU,CAAC;IAC5D,OAAO,YAAY,CAAC,KAAK,EAAE,GAAG,CAAC,IAAI,GAAG,CAAC,OAAO,EAAE,GAAG,aAAa,CAAC,OAAO,EAAE,GAAG,eAAe,CAAC;AAC/F,CAAC;AAED,MAAM,aAAa,GAAG,IAAI,CAAC;AAE3B,iIAAiI;AACjI,MAAM,UAAU,mBAAmB,CAAC,GAAS,EAAE,gBAA+B;IAC5E,OAAO,gBAAgB,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,gBAAgB,GAAG,aAAa,CAAC,CAAC;AACvG,CAAC"}

package/dist/core/party-grants/ports.d.ts

@@ -0,0 +1,180 @@
+/**
+ * The ports of a person's sign-in to an outside MCP server that takes only
+ * an OAuth sign-in (decision 0067): the grants the gateway keeps, the sign-in
+ * under way sealed into its state, and the party's authorization server.
+ */
+import type { FleetId, ShipId } from '@aeolus-fleet/common';
+import type { ActorCredential } from '../actors/credential-of.js';
+import type { FleetRefusal } from '../connection/ports.js';
+import type { Result } from '../shared/result.js';
+import type { SignInClient } from '../vault/credential.js';
+import type { PartyGrant } from './party-grant.js';
+/** An outside MCP server as a person's sign-in sees it: its sign-in client where each person signs in, none where the gateway calls it with its own credential. */
+export interface SignInServer {
+    readonly fleetId: FleetId;
+    readonly name: string;
+    readonly client: SignInClient | null;
+}
+/** Outbound port: the outside MCP servers of a fleet, by the name of their proxy ship. */
+export interface SignInServers {
+    /** The outside MCP server of this name; none when the name is no outside MCP server. */
+    find(fleetId: FleetId, name: string): Promise<SignInServer | undefined>;
+}
+/** Outbound port: states what a server's proxy ship offers, from the grants now kept (Q15); the refusal says why the statement waits. */
+export type StatesProxyShip = (input: {
+    fleetId: FleetId;
+    name: string;
+}) => Promise<Result<unknown, {
+    readonly message: string;
+}>>;
+/** Outbound port: the names of the fleet's ships, as the actor reads them, in one read for a page of them; a ship the fleet does not answer is left out. */
+export interface ShipNames {
+    namesOf(as: ActorCredential, shipIds: readonly ShipId[]): Promise<Result<ReadonlyMap<ShipId, string>, FleetRefusal>>;
+}
+/** Outbound port: every person's grant of each party, in the gateway's database. */
+export interface PartyGrants {
+    ofPerson(fleetId: FleetId, grant: {
+        party: string;
+        personShipId: ShipId;
+    }): Promise<PartyGrant | undefined>;
+    /** The grants of the party, by person ship, after the person ship named, at most as many as asked. */
+    ofParty(fleetId: FleetId, asked: {
+        party: string;
+        after: ShipId | null;
+        limit: number;
+    }): Promise<PartyGrant[]>;
+    /** Every person holding a grant, in every fleet, each once. */
+    persons(): Promise<{
+        fleetId: FleetId;
+        personShipId: ShipId;
+    }[]>;
+    /** Every grant of the person, one per party at most. */
+    ofPersonShip(fleetId: FleetId, personShipId: ShipId): Promise<PartyGrant[]>;
+    /** Every grant of the account in the fleet, one per party at most. */
+    ofAccount(fleetId: FleetId, accountId: string): Promise<PartyGrant[]>;
+    /** The grant of the party that names this outside account, whoever holds it. */
+    ofSubject(fleetId: FleetId, grant: {
+        party: string;
+        subject: string;
+    }): Promise<PartyGrant | undefined>;
+    /** A grant of the party whose access token may still be sent, the most recently used first, then the most recently signed in (Q15). */
+    usable(fleetId: FleetId, asked: {
+        party: string;
+        now: Date;
+    }): Promise<PartyGrant | undefined>;
+    /** Keeps the grant in place of the person's earlier one; none kept when another person's grant of the party names its outside account, as two sign-ins at once find. */
+    keep(grant: PartyGrant): Promise<'kept' | 'subjectTaken'>;
+    /**
+     * Holds the person's grant while the change runs, so one change at a time
+     * runs on it, also across gateway instances, and keeps the grant it
+     * answers before another change reads it; none when the person holds no
+     * grant of the party.
+     */
+    change(grant: Pick<PartyGrant, 'fleetId' | 'party' | 'personShipId'>, change: (held: PartyGrant) => Promise<PartyGrant>): Promise<PartyGrant | undefined>;
+    /** The grants of every fleet the schedule refreshes now (Q7), at most a round's worth, those whose access token ends first first. */
+    due(asked: {
+        now: Date;
+    }): Promise<PartyGrant[]>;
+    /** Sets when the person's grant last served a call. */
+    markUsed(grant: Pick<PartyGrant, 'fleetId' | 'party' | 'personShipId'>, at: Date): Promise<void>;
+    remove(fleetId: FleetId, grant: {
+        party: string;
+        personShipId: ShipId;
+    }): Promise<void>;
+}
+/** A person's sign-in to a party under way at its authorization server: whose it is, and its PKCE verifier. */
+export interface PartySignInUnderWay {
+    readonly fleetId: FleetId;
+    readonly party: string;
+    readonly accountId: string;
+    readonly personShipId: ShipId;
+    readonly verifier: string;
+    readonly expiresAt: Date;
+}
+/** Outbound port: seals a sign-in under way into the state the authorization server carries back, so the gateway stores nothing for it. */
+export interface PartySignInSeals {
+    seal(signIn: PartySignInUnderWay): string;
+    /** The sign-in a state seals; none for a state the gateway did not seal. */
+    open(state: string): PartySignInUnderWay | undefined;
+}
+/** What an OpenID Connect ID token claims, read and not yet checked: the core checks it names the party's issuer and client. */
+export interface IdTokenClaims {
+    readonly issuer: string;
+    readonly audiences: readonly string[];
+    readonly subject: string;
+    readonly name: string | null;
+}
+/** The token endpoint's answer to a redeemed code. */
+export interface RedeemedTokens {
+    readonly accessToken: string;
+    readonly refreshToken: string | null;
+    readonly expiresInSeconds: number | null;
+    /** None when the authorization server sent no ID token. */
+    readonly idToken: IdTokenClaims | null;
+}
+/** The token endpoint's answer to a refresh (RFC 6749 6): a new refresh token only where the server rotates them. */
+export type RefreshedTokens = Omit<RedeemedTokens, 'idToken'>;
+/**
+ * Why a token request gave no tokens: the authorization server answered an
+ * OAuth error (refused, with its error code), or did not answer
+ * (unreachable).
+ */
+export type TokenRequestFailure = {
+    readonly kind: 'refused';
+    readonly error: string;
+    readonly reason: string;
+} | {
+    readonly kind: 'unreachable';
+    readonly reason: string;
+};
+/** Outbound port: a party's authorization server, reached with the party's client. */
+export interface PartySignIns {
+    /** The authorize address a person's browser goes to: the code flow with PKCE S256, the client's scope and resource (RFC 8707). */
+    authorizeUrl(client: SignInClient, asked: {
+        state: string;
+        codeChallenge: string;
+        redirectUri: string;
+    }): string;
+    redeemCode(client: SignInClient, asked: {
+        code: string;
+        verifier: string;
+        redirectUri: string;
+    }): Promise<Result<RedeemedTokens, TokenRequestFailure>>;
+    refresh(client: SignInClient, refreshToken: string): Promise<Result<RefreshedTokens, TokenRequestFailure>>;
+    /** Revokes a token at the client's revocation endpoint (RFC 7009). */
+    revoke(client: SignInClient & {
+        revocationEndpoint: string;
+    }, token: string): Promise<Result<void, {
+        reason: string;
+    }>>;
+    /** Deletes the client at its client configuration endpoint, with its registration access token (RFC 7592). */
+    deleteClient(client: SignInClient & {
+        registrationClientUri: string;
+        registrationAccessToken: string;
+    }): Promise<Result<void, {
+        reason: string;
+    }>>;
+}
+/** The notice a person is told by when a call needs their sign-in to a party (Q6): its id keys the message, so one sent again is stored once. */
+export interface SignInNotice {
+    readonly noticeId: string;
+    readonly isTold: boolean;
+}
+/** Outbound port: the notices of a missing sign-in, one per person and party while open. */
+export interface SignInNotices {
+    /** The person's open notice for the party, opened under this id unless one is open already, as two calls at once find. */
+    open(fleetId: FleetId, notice: {
+        party: string;
+        personShipId: ShipId;
+        noticeId: string;
+    }): Promise<SignInNotice>;
+    markTold(fleetId: FleetId, notice: {
+        party: string;
+        personShipId: ShipId;
+    }): Promise<void>;
+    /** Closes it at a sign-in, so a later loss tells the person again (Q6). */
+    close(fleetId: FleetId, notice: {
+        party: string;
+        personShipId: ShipId;
+    }): Promise<void>;
+}

package/dist/core/party-grants/ports.js

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

package/dist/core/party-grants/ports.js.map

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

package/dist/core/party-grants/read-own-grant.d.ts

@@ -0,0 +1,33 @@
+import type { Actor } from '../actors/authenticate-actor.js';
+import { type Result } from '../shared/result.js';
+import type { GrantLost, OutsideAccount, PartyGrant } from './party-grant.js';
+import type { PartyGrants, SignInServers } from './ports.js';
+import { type SignInPartyRefusal } from './sign-in-party.js';
+interface HeldGrant {
+    readonly outsideAccount: OutsideAccount;
+    readonly signedInAt: Date;
+    readonly lastUsedAt: Date | null;
+}
+/** A person's own sign-in to a party, as their page shows it: never a token. A lost one says when and why (Q5). */
+export type OwnGrant = {
+    readonly state: 'notSignedIn';
+} | ({
+    readonly state: 'signedIn';
+} & HeldGrant) | ({
+    readonly state: 'lost';
+    readonly lost: GrantLost;
+} & HeldGrant);
+export type ReadOwnGrant = (input: {
+    actor: Actor;
+    name: string;
+}) => Promise<Result<OwnGrant, SignInPartyRefusal>>;
+/** Use case: a person reads their own sign-in to an outside MCP server where each person signs in (decision 0067, Q12): the outside account it names, when they signed in, when it was last used, and whether it was lost. */
+export declare function createReadOwnGrant(deps: {
+    servers: SignInServers;
+    grants: Pick<PartyGrants, 'ofPerson'>;
+}): ReadOwnGrant;
+/** A held grant as a page shows it: never a token. */
+export declare function shownGrantOf(grant: PartyGrant): Exclude<OwnGrant, {
+    state: 'notSignedIn';
+}>;
+export {};

package/dist/core/party-grants/read-own-grant.js

@@ -0,0 +1,23 @@
+import { ok } from '../shared/result.js';
+import { signInPartyOf } from './sign-in-party.js';
+/** Use case: a person reads their own sign-in to an outside MCP server where each person signs in (decision 0067, Q12): the outside account it names, when they signed in, when it was last used, and whether it was lost. */
+export function createReadOwnGrant(deps) {
+    return async (input) => {
+        const signingIn = await signInPartyOf(deps.servers, input);
+        if (!signingIn.isOk) {
+            return signingIn;
+        }
+        const { server, personShipId } = signingIn.value;
+        const grant = await deps.grants.ofPerson(server.fleetId, { party: server.name, personShipId });
+        if (grant === undefined) {
+            return ok({ state: 'notSignedIn' });
+        }
+        return ok(shownGrantOf(grant));
+    };
+}
+/** A held grant as a page shows it: never a token. */
+export function shownGrantOf(grant) {
+    const { outsideAccount, signedInAt, lastUsedAt, lost } = grant;
+    return lost === null ? { state: 'signedIn', outsideAccount, signedInAt, lastUsedAt } : { state: 'lost', outsideAccount, signedInAt, lastUsedAt, lost };
+}
+//# sourceMappingURL=read-own-grant.js.map

package/dist/core/party-grants/read-own-grant.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-own-grant.js","sourceRoot":"","sources":["../../../src/core/party-grants/read-own-grant.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,EAAE,EAAe,MAAM,qBAAqB,CAAC;AAGtD,OAAO,EAAE,aAAa,EAA2B,MAAM,oBAAoB,CAAC;AAa5E,8NAA8N;AAC9N,MAAM,UAAU,kBAAkB,CAAC,IAAuE;IACxG,OAAO,KAAK,EAAE,KAAK,EAAE,EAAE;QACrB,MAAM,SAAS,GAAG,MAAM,aAAa,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QAC3D,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC;YACpB,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,GAAG,SAAS,CAAC,KAAK,CAAC;QACjD,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,IAAI,EAAE,YAAY,EAAE,CAAC,CAAC;QAC/F,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,OAAO,EAAE,CAAC,EAAE,KAAK,EAAE,aAAa,EAAE,CAAC,CAAC;QACtC,CAAC;QACD,OAAO,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC;IACjC,CAAC,CAAC;AACJ,CAAC;AAED,sDAAsD;AACtD,MAAM,UAAU,YAAY,CAAC,KAAiB;IAC5C,MAAM,EAAE,cAAc,EAAE,UAAU,EAAE,UAAU,EAAE,IAAI,EAAE,GAAG,KAAK,CAAC;IAC/D,OAAO,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,UAAU,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,UAAU,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;AACzJ,CAAC"}

package/dist/core/party-grants/refresh-grant.d.ts

@@ -0,0 +1,41 @@
+import type { Clock } from '../shared/clock.js';
+import { type Result } from '../shared/result.js';
+import type { SignInClient } from '../vault/credential.js';
+import { type GrantLost, type PartyGrant } from './party-grant.js';
+import type { PartyGrants, PartySignIns, TokenRequestFailure } from './ports.js';
+import type { TellSignInNeeded } from './tell-sign-in-needed.js';
+/**
+ * Why a grant was not refreshed: it holds no refresh token; the
+ * authorization server refused or did not answer the refresh; the grant is
+ * lost, the server having answered `invalid_grant`; or the person holds no
+ * grant of the party any more.
+ */
+export type RefreshFailure = {
+    readonly kind: 'noRefreshToken';
+} | TokenRequestFailure | {
+    readonly kind: 'lost';
+    readonly lost: GrantLost;
+} | {
+    readonly kind: 'removed';
+};
+export type RefreshGrant = (input: {
+    client: SignInClient;
+    grant: PartyGrant;
+}) => Promise<Result<PartyGrant, RefreshFailure>>;
+/**
+ * Use case: a person's grant is refreshed with its party's client (decision
+ * 0067, Q7), one refresh at a time per grant: the grant is held while its
+ * refresh runs, and the new tokens are kept before they are used (L19). A
+ * grant whose access token is no longer the one asked for was refreshed, or
+ * signed in again, meanwhile: it is answered as held, refreshing nothing, so
+ * a rotated refresh token is never used twice. A server that issues no new
+ * refresh token leaves the one held. A refresh answered `invalid_grant`
+ * loses the grant, kept with when and why, and tells the person once (Q5,
+ * Q6); any other refusal keeps it as it was.
+ */
+export declare function createRefreshGrant(deps: {
+    signIns: Pick<PartySignIns, 'refresh'>;
+    grants: Pick<PartyGrants, 'change'>;
+    tellSignInNeeded: TellSignInNeeded;
+    clock: Clock;
+}): RefreshGrant;

package/dist/core/party-grants/refresh-grant.js

@@ -0,0 +1,58 @@
+import { err, ok } from '../shared/result.js';
+import { accessTokenEndsAtOf } from './party-grant.js';
+/** The OAuth error a refresh token the authorization server will not refresh again is refused with (RFC 6749 5.2). */
+const INVALID_GRANT = 'invalid_grant';
+/**
+ * Use case: a person's grant is refreshed with its party's client (decision
+ * 0067, Q7), one refresh at a time per grant: the grant is held while its
+ * refresh runs, and the new tokens are kept before they are used (L19). A
+ * grant whose access token is no longer the one asked for was refreshed, or
+ * signed in again, meanwhile: it is answered as held, refreshing nothing, so
+ * a rotated refresh token is never used twice. A server that issues no new
+ * refresh token leaves the one held. A refresh answered `invalid_grant`
+ * loses the grant, kept with when and why, and tells the person once (Q5,
+ * Q6); any other refusal keeps it as it was.
+ */
+export function createRefreshGrant(deps) {
+    return async ({ client, grant }) => {
+        let failure;
+        const losing = { lost: null };
+        const refreshed = async (held) => {
+            if (held.lost !== null) {
+                failure = { kind: 'lost', lost: held.lost };
+                return held;
+            }
+            if (held.accessToken !== grant.accessToken) {
+                return held;
+            }
+            if (held.refreshToken === null) {
+                failure = { kind: 'noRefreshToken' };
+                return held;
+            }
+            const answered = await deps.signIns.refresh(client, held.refreshToken);
+            if (!answered.isOk) {
+                if (answered.error.kind === 'refused' && answered.error.error === INVALID_GRANT) {
+                    const lost = { at: deps.clock.now(), why: answered.error.reason };
+                    failure = { kind: 'lost', lost };
+                    losing.lost = lost;
+                    return { ...held, lost };
+                }
+                failure = answered.error;
+                return held;
+            }
+            const { accessToken, refreshToken, expiresInSeconds } = answered.value;
+            const now = deps.clock.now();
+            return { ...held, accessToken, refreshToken: refreshToken ?? held.refreshToken, accessTokenEndsAt: accessTokenEndsAtOf(now, expiresInSeconds), refreshedAt: now };
+        };
+        const kept = await deps.grants.change(grant, refreshed);
+        if (kept === undefined) {
+            return err({ kind: 'removed' });
+        }
+        if (losing.lost !== null) {
+            // Told once the loss is kept, never while the grant is held.
+            await deps.tellSignInNeeded({ fleetId: kept.fleetId, party: kept.party, personShipId: kept.personShipId, lost: losing.lost });
+        }
+        return failure === undefined ? ok(kept) : err(failure);
+    };
+}
+//# sourceMappingURL=refresh-grant.js.map

package/dist/core/party-grants/refresh-grant.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refresh-grant.js","sourceRoot":"","sources":["../../../src/core/party-grants/refresh-grant.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,GAAG,EAAE,EAAE,EAAe,MAAM,qBAAqB,CAAC;AAE3D,OAAO,EAAE,mBAAmB,EAAmC,MAAM,kBAAkB,CAAC;AAIxF,sHAAsH;AACtH,MAAM,aAAa,GAAG,eAAe,CAAC;AAYtC;;;;;;;;;;GAUG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAuI;IACxK,OAAO,KAAK,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,EAAE;QACjC,IAAI,OAAmC,CAAC;QACxC,MAAM,MAAM,GAA+B,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;QAC1D,MAAM,SAAS,GAAG,KAAK,EAAE,IAAgB,EAAuB,EAAE;YAChE,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;gBACvB,OAAO,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC;gBAC5C,OAAO,IAAI,CAAC;YACd,CAAC;YACD,IAAI,IAAI,CAAC,WAAW,KAAK,KAAK,CAAC,WAAW,EAAE,CAAC;gBAC3C,OAAO,IAAI,CAAC;YACd,CAAC;YACD,IAAI,IAAI,CAAC,YAAY,KAAK,IAAI,EAAE,CAAC;gBAC/B,OAAO,GAAG,EAAE,IAAI,EAAE,gBAAgB,EAAE,CAAC;gBACrC,OAAO,IAAI,CAAC;YACd,CAAC;YACD,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC;YACvE,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;gBACnB,IAAI,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,SAAS,IAAI,QAAQ,CAAC,KAAK,CAAC,KAAK,KAAK,aAAa,EAAE,CAAC;oBAChF,MAAM,IAAI,GAAG,EAAE,EAAE,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,EAAE,GAAG,EAAE,QAAQ,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;oBAClE,OAAO,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;oBACjC,MAAM,CAAC,IAAI,GAAG,IAAI,CAAC;oBACnB,OAAO,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,CAAC;gBAC3B,CAAC;gBACD,OAAO,GAAG,QAAQ,CAAC,KAAK,CAAC;gBACzB,OAAO,IAAI,CAAC;YACd,CAAC;YACD,MAAM,EAAE,WAAW,EAAE,YAAY,EAAE,gBAAgB,EAAE,GAAG,QAAQ,CAAC,KAAK,CAAC;YACvE,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC;YAC7B,OAAO,EAAE,GAAG,IAAI,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,IAAI,IAAI,CAAC,YAAY,EAAE,iBAAiB,EAAE,mBAAmB,CAAC,GAAG,EAAE,gBAAgB,CAAC,EAAE,WAAW,EAAE,GAAG,EAAE,CAAC;QACpK,CAAC,CAAC;QACF,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;QACxD,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,OAAO,GAAG,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC;QAClC,CAAC;QACD,IAAI,MAAM,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;YACzB,6DAA6D;YAC7D,MAAM,IAAI,CAAC,gBAAgB,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,YAAY,EAAE,IAAI,CAAC,YAAY,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;QAChI,CAAC;QACD,OAAO,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACzD,CAAC,CAAC;AACJ,CAAC"}

package/dist/core/party-grants/remove-grant.d.ts

@@ -0,0 +1,21 @@
+import type { ShipId } from '@aeolus-fleet/common';
+import type { ApprovingDeps, CheckApproving } from '../parties/check-approving.js';
+import { type DomainError } from '../shared/errors.js';
+import { type Result } from '../shared/result.js';
+import { type ApprovedSignInPartyRefusal } from './approved-sign-in-party.js';
+import type { PartyGrants, PartySignIns } from './ports.js';
+export type RemoveGrant = (input: Parameters<CheckApproving>[0] & {
+    personShipId: ShipId;
+}) => Promise<Result<{
+    isRevoked: boolean;
+}, ApprovedSignInPartyRefusal | DomainError<'NOT_SIGNED_IN'>>>;
+/**
+ * Use case: an actor holding gateway:approve within manage reach of an
+ * outside MCP server's proxy ship removes any person's sign-in to it
+ * (decision 0067, Q6), so the party is cut off for that person without
+ * retiring it. It ends as every grant ends.
+ */
+export declare function createRemoveGrant(deps: ApprovingDeps & {
+    grants: Pick<PartyGrants, 'ofPerson' | 'remove'>;
+    signIns: Pick<PartySignIns, 'revoke'>;
+}): RemoveGrant;

package/dist/core/party-grants/remove-grant.js

@@ -0,0 +1,25 @@
+import { refuse } from '../shared/errors.js';
+import { ok } from '../shared/result.js';
+import { approvedSignInParty } from './approved-sign-in-party.js';
+import { endGrant } from './end-grant.js';
+/**
+ * Use case: an actor holding gateway:approve within manage reach of an
+ * outside MCP server's proxy ship removes any person's sign-in to it
+ * (decision 0067, Q6), so the party is cut off for that person without
+ * retiring it. It ends as every grant ends.
+ */
+export function createRemoveGrant(deps) {
+    return async ({ personShipId, ...asked }) => {
+        const approved = await approvedSignInParty(deps, asked);
+        if (!approved.isOk) {
+            return approved;
+        }
+        const { name, client } = approved.value;
+        const grant = await deps.grants.ofPerson(asked.actor.fleetId, { party: name, personShipId });
+        if (grant === undefined) {
+            return refuse('NOT_SIGNED_IN', `${personShipId} is not signed in to ${name}`);
+        }
+        return ok({ isRevoked: await endGrant(deps, { client, grant }) });
+    };
+}
+//# sourceMappingURL=remove-grant.js.map

package/dist/core/party-grants/remove-grant.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remove-grant.js","sourceRoot":"","sources":["../../../src/core/party-grants/remove-grant.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,MAAM,EAAoB,MAAM,qBAAqB,CAAC;AAC/D,OAAO,EAAE,EAAE,EAAe,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,mBAAmB,EAAmC,MAAM,6BAA6B,CAAC;AACnG,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAO1C;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAiH;IACjJ,OAAO,KAAK,EAAE,EAAE,YAAY,EAAE,GAAG,KAAK,EAAE,EAAE,EAAE;QAC1C,MAAM,QAAQ,GAAG,MAAM,mBAAmB,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACxD,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;YACnB,OAAO,QAAQ,CAAC;QAClB,CAAC;QACD,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,QAAQ,CAAC,KAAK,CAAC;QACxC,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC,CAAC;QAC7F,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,OAAO,MAAM,CAAC,eAAe,EAAE,GAAG,YAAY,wBAAwB,IAAI,EAAE,CAAC,CAAC;QAChF,CAAC;QACD,OAAO,EAAE,CAAC,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;IACpE,CAAC,CAAC;AACJ,CAAC"}

package/dist/core/party-grants/remove-own-grant.d.ts

@@ -0,0 +1,17 @@
+import type { Actor } from '../actors/authenticate-actor.js';
+import { type DomainError } from '../shared/errors.js';
+import { type Result } from '../shared/result.js';
+import type { PartyGrants, PartySignIns, SignInServers } from './ports.js';
+import { type SignInPartyRefusal } from './sign-in-party.js';
+export type RemoveOwnGrant = (input: {
+    actor: Actor;
+    name: string;
+}) => Promise<Result<{
+    isRevoked: boolean;
+}, SignInPartyRefusal | DomainError<'NOT_SIGNED_IN'>>>;
+/** Use case: a person removes their own sign-in to an outside MCP server (decision 0067, Q6), ended as every grant ends. */
+export declare function createRemoveOwnGrant(deps: {
+    servers: SignInServers;
+    grants: Pick<PartyGrants, 'ofPerson' | 'remove'>;
+    signIns: Pick<PartySignIns, 'revoke'>;
+}): RemoveOwnGrant;

package/dist/core/party-grants/remove-own-grant.js

@@ -0,0 +1,21 @@
+import { refuse } from '../shared/errors.js';
+import { ok } from '../shared/result.js';
+import { endGrant } from './end-grant.js';
+import { signInPartyOf } from './sign-in-party.js';
+/** Use case: a person removes their own sign-in to an outside MCP server (decision 0067, Q6), ended as every grant ends. */
+export function createRemoveOwnGrant(deps) {
+    return async (input) => {
+        const signingIn = await signInPartyOf(deps.servers, input);
+        if (!signingIn.isOk) {
+            return signingIn;
+        }
+        const { server, client, personShipId } = signingIn.value;
+        const grant = await deps.grants.ofPerson(server.fleetId, { party: server.name, personShipId });
+        if (grant === undefined) {
+            return refuse('NOT_SIGNED_IN', `You are not signed in to ${server.name}`);
+        }
+        const isRevoked = await endGrant(deps, { client, grant });
+        return ok({ isRevoked });
+    };
+}
+//# sourceMappingURL=remove-own-grant.js.map

package/dist/core/party-grants/remove-own-grant.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remove-own-grant.js","sourceRoot":"","sources":["../../../src/core/party-grants/remove-own-grant.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAoB,MAAM,qBAAqB,CAAC;AAC/D,OAAO,EAAE,EAAE,EAAe,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C,OAAO,EAAE,aAAa,EAA2B,MAAM,oBAAoB,CAAC;AAI5E,4HAA4H;AAC5H,MAAM,UAAU,oBAAoB,CAAC,IAAyH;IAC5J,OAAO,KAAK,EAAE,KAAK,EAAE,EAAE;QACrB,MAAM,SAAS,GAAG,MAAM,aAAa,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QAC3D,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC;YACpB,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,GAAG,SAAS,CAAC,KAAK,CAAC;QACzD,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,IAAI,EAAE,YAAY,EAAE,CAAC,CAAC;QAC/F,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,OAAO,MAAM,CAAC,eAAe,EAAE,4BAA4B,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;QAC5E,CAAC;QACD,MAAM,SAAS,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;QAC1D,OAAO,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC;IAC3B,CAAC,CAAC;AACJ,CAAC"}

package/dist/core/party-grants/sign-in-party.d.ts

@@ -0,0 +1,23 @@
+import type { ShipId } from '@aeolus-fleet/common';
+import type { Actor } from '../actors/authenticate-actor.js';
+import { type DomainError } from '../shared/errors.js';
+import { type Result } from '../shared/result.js';
+import type { SignInClient } from '../vault/credential.js';
+import type { SignInServer, SignInServers } from './ports.js';
+export type SignInPartyRefusal = DomainError<'NOT_A_PERSON' | 'NO_SUCH_PARTY' | 'NO_SIGN_IN'>;
+/** A person acting on their own sign-in to a party, and the party's client. */
+export interface SignInParty {
+    readonly server: SignInServer;
+    readonly client: SignInClient;
+    readonly accountId: string;
+    readonly personShipId: ShipId;
+}
+/**
+ * The party an account signs in to for itself (decision 0067, Q16): only an
+ * account with a person ship in the fleet, and only an outside MCP server
+ * where each person signs in.
+ */
+export declare function signInPartyOf(servers: SignInServers, asked: {
+    actor: Actor;
+    name: string;
+}): Promise<Result<SignInParty, SignInPartyRefusal>>;

package/dist/core/party-grants/sign-in-party.js

@@ -0,0 +1,22 @@
+import { refuse } from '../shared/errors.js';
+import { ok } from '../shared/result.js';
+/**
+ * The party an account signs in to for itself (decision 0067, Q16): only an
+ * account with a person ship in the fleet, and only an outside MCP server
+ * where each person signs in.
+ */
+export async function signInPartyOf(servers, asked) {
+    const { actor, name } = asked;
+    if (actor.kind !== 'account' || actor.personShipId === null) {
+        return refuse('NOT_A_PERSON', 'Only a person signs in to an outside server, and your account has no person ship in this fleet');
+    }
+    const server = await servers.find(actor.fleetId, name);
+    if (server === undefined) {
+        return refuse('NO_SUCH_PARTY', `There is no outside MCP server ${name}`);
+    }
+    if (server.client === null) {
+        return refuse('NO_SIGN_IN', `Nobody signs in to ${name} for themselves: the gateway calls it with its own credential`);
+    }
+    return ok({ server, client: server.client, accountId: actor.accountId, personShipId: actor.personShipId });
+}
+//# sourceMappingURL=sign-in-party.js.map

package/dist/core/party-grants/sign-in-party.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sign-in-party.js","sourceRoot":"","sources":["../../../src/core/party-grants/sign-in-party.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,MAAM,EAAoB,MAAM,qBAAqB,CAAC;AAC/D,OAAO,EAAE,EAAE,EAAe,MAAM,qBAAqB,CAAC;AActD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,OAAsB,EAAE,KAAqC;IAC/F,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,KAAK,CAAC;IAC9B,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,IAAI,KAAK,CAAC,YAAY,KAAK,IAAI,EAAE,CAAC;QAC5D,OAAO,MAAM,CAAC,cAAc,EAAE,gGAAgG,CAAC,CAAC;IAClI,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IACvD,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,OAAO,MAAM,CAAC,eAAe,EAAE,kCAAkC,IAAI,EAAE,CAAC,CAAC;IAC3E,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC;QAC3B,OAAO,MAAM,CAAC,YAAY,EAAE,sBAAsB,IAAI,+DAA+D,CAAC,CAAC;IACzH,CAAC;IACD,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,YAAY,EAAE,KAAK,CAAC,YAAY,EAAE,CAAC,CAAC;AAC7G,CAAC"}

package/dist/core/party-grants/start-party-sign-in.d.ts

@@ -0,0 +1,31 @@
+import type { Actor } from '../actors/authenticate-actor.js';
+import type { OAuthSecrets } from '../oauth/ports.js';
+import type { Clock } from '../shared/clock.js';
+import { type Result } from '../shared/result.js';
+import type { PartySignIns, PartySignInSeals, SignInServers } from './ports.js';
+import { type SignInPartyRefusal } from './sign-in-party.js';
+/** How long a sign-in the gateway started may take to come back from the outside authorization server. */
+export declare const PARTY_SIGN_IN_MS: number;
+export type StartPartySignInRefusal = SignInPartyRefusal;
+export type StartPartySignIn = (input: {
+    actor: Actor;
+    name: string;
+}) => Promise<Result<{
+    url: string;
+}, StartPartySignInRefusal>>;
+/**
+ * Use case: a person presses Sign in on an outside MCP server's page, for
+ * themselves (decision 0067, Q16): every account of the fleet with a person
+ * ship may. The gateway seals whose sign-in it is and its PKCE verifier into
+ * the state, for ten minutes, and sends the person to the party's
+ * authorization server under the party's client.
+ */
+export declare function createStartPartySignIn(deps: {
+    servers: SignInServers;
+    seals: PartySignInSeals;
+    signIns: Pick<PartySignIns, 'authorizeUrl'>;
+    secrets: Pick<OAuthSecrets, 'newSecret' | 'challengeOf'>;
+    clock: Clock;
+    /** Where the authorization server sends the person back: the redirect URI the party's client was registered with. */
+    redirectUri: string;
+}): StartPartySignIn;