fluxmail 0.16.0 → 0.17.1

package/dist/storage/oauth.d.ts

@@ -0,0 +1,178 @@
+import { type FluxmailDb } from './db.js';
+import type { MemberRole } from './members.js';
+import { type McpCapability } from '../permissions.js';
+export declare const OAUTH_ACCESS_TOKEN_TTL_MS: number;
+export declare const OAUTH_REFRESH_TOKEN_TTL_MS: number;
+export declare const OAUTH_GRANT_TTL_MS: number;
+export declare const OAUTH_CODE_TTL_MS: number;
+export declare const OAUTH_REQUEST_TTL_MS: number;
+export declare const OAUTH_MAX_CLIENTS = 1000;
+export declare const OAUTH_MAX_CLIENTS_PER_HOST = 20;
+export declare const OFFLINE_ACCESS_SCOPE = "offline_access";
+export declare const OAUTH_SCOPES: readonly ["mail.read", "mail.drafts", "mail.organize", "mail.trash", "mail.delete", "mail.send", "offline_access"];
+export type OAuthScope = (typeof OAUTH_SCOPES)[number];
+export type OAuthClientKind = 'registered' | 'metadata_document';
+export interface OAuthClient {
+    id: string;
+    kind: OAuthClientKind;
+    name: string;
+    redirectUris: string[];
+    /** Mail scopes the client may request. */
+    scopes: McpCapability[];
+    metadataHost: string | null;
+    metadataExpiresAt: number | null;
+    createdAt: number;
+    lastUsedAt: number | null;
+}
+export interface OAuthGrantInfo {
+    id: string;
+    clientId: string;
+    clientName: string;
+    clientKind: OAuthClientKind;
+    memberId: string;
+    scopes: McpCapability[];
+    /** Mailbox narrowing. null means every mailbox available to the member. */
+    accountIds: string[] | null;
+    createdAt: number;
+    expiresAt: number;
+    lastUsedAt: number | null;
+}
+export interface OAuthAuthorizationRequest {
+    id: string;
+    clientId: string;
+    redirectUri: string;
+    state: string | null;
+    codeChallenge: string;
+    scopes: OAuthScope[];
+    memberId: string | null;
+    expiresAt: number;
+}
+export interface OAuthTokenSet {
+    accessToken: string;
+    refreshToken?: string;
+    expiresIn: number;
+    scopes: OAuthScope[];
+}
+export type OAuthTokenResult = {
+    ok: true;
+    tokens: OAuthTokenSet;
+} | {
+    ok: false;
+    error: 'invalid_grant' | 'invalid_scope';
+    description: string;
+};
+export interface OAuthAccessTokenAuth {
+    grantId: string;
+    clientId: string;
+    memberId: string;
+    role: MemberRole;
+    scopes: McpCapability[];
+    accountIds: string[] | null;
+}
+export declare function isOAuthScope(value: string): value is OAuthScope;
+/** Keep known scopes in canonical order. */
+export declare function canonicalOAuthScopes(scopes: Iterable<string>): OAuthScope[];
+export declare function mailScopesOf(scopes: Iterable<string>): McpCapability[];
+/** Remove expired protocol state, ended grants, and clients nobody uses. */
+export declare function pruneOAuthState(db: FluxmailDb, now?: number): void;
+/**
+ * Count an attempt in a fixed window shared across processes. Returns false
+ * once the limit is reached.
+ */
+export declare function reserveOAuthRateLimit(db: FluxmailDb, name: string, limit: number, windowMs: number, now?: number): boolean;
+/** Store a dynamically registered public client. Returns null when the client limit is reached. */
+export declare function registerOAuthClient(db: FluxmailDb, input: {
+    name: string;
+    redirectUris: readonly string[];
+    scopes: readonly McpCapability[];
+}, now?: number): OAuthClient | null;
+export type MetadataClientResult = {
+    status: 'stored';
+    client: OAuthClient;
+} | {
+    status: 'limit';
+};
+/**
+ * Create or refresh a client described by a metadata document. New clients
+ * count toward the global and per-host limits.
+ */
+export declare function storeMetadataOAuthClient(db: FluxmailDb, input: {
+    id: string;
+    host: string;
+    name: string;
+    redirectUris: readonly string[];
+    expiresAt: number;
+}, now?: number): MetadataClientResult;
+export declare function getOAuthClient(db: FluxmailDb, id: string): OAuthClient | null;
+export declare function countOAuthClients(db: FluxmailDb, host?: string): number;
+/** Save a validated authorization request. The CSRF token is returned once. */
+export declare function createOAuthAuthorizationRequest(db: FluxmailDb, input: {
+    clientId: string;
+    redirectUri: string;
+    state?: string;
+    codeChallenge: string;
+    scopes: readonly OAuthScope[];
+}, now?: number): {
+    request: OAuthAuthorizationRequest;
+    csrf: string;
+};
+/** Find an unexpired request whose CSRF token matches. */
+export declare function getOAuthAuthorizationRequest(db: FluxmailDb, id: string, csrf: string, now?: number): OAuthAuthorizationRequest | null;
+/** Record the signed-in member on a request and rotate its CSRF token. */
+export declare function signInOAuthAuthorizationRequest(db: FluxmailDb, id: string, memberId: string, now?: number): string | null;
+export declare function deleteOAuthAuthorizationRequest(db: FluxmailDb, id: string): void;
+/**
+ * Turn a signed-in request into a grant and a single-use authorization code.
+ * The request is deleted in the same transaction, so it cannot be approved twice.
+ */
+export declare function approveOAuthAuthorizationRequest(db: FluxmailDb, input: {
+    requestId: string;
+    memberId: string;
+    scopes: readonly McpCapability[];
+    accountIds: readonly string[] | null;
+}, now?: number): {
+    code: string;
+    grantId: string;
+    redirectUri: string;
+    state: string | null;
+} | null;
+type Tx = Parameters<Parameters<FluxmailDb['transaction']>[0]>[0];
+/** Exchange an authorization code. Replaying a used code revokes its grant. */
+export declare function exchangeOAuthAuthorizationCode(db: FluxmailDb, input: {
+    code: string;
+    clientId: string;
+    redirectUri: string;
+    codeVerifier: string;
+}, now?: number): OAuthTokenResult;
+/**
+ * Rotate a refresh token. Reusing a rotated token revokes the grant. A refresh
+ * can keep or narrow its scopes but never add one.
+ */
+export declare function refreshOAuthTokens(db: FluxmailDb, input: {
+    refreshToken: string;
+    clientId: string;
+    scopes?: readonly string[];
+}, now?: number): OAuthTokenResult;
+/**
+ * Revoke the grant behind a token when the token belongs to the client.
+ * Unknown tokens are ignored, as RFC 7009 requires.
+ */
+export declare function revokeOAuthToken(db: FluxmailDb, input: {
+    token: string;
+    clientId: string;
+}, now?: number): void;
+/** Verify an access token against its live grant and member. */
+export declare function authenticateOAuthAccessToken(db: FluxmailDb, token: string, now?: number): OAuthAccessTokenAuth | null;
+/** Active grants, optionally for one member, newest first. */
+export declare function listOAuthGrants(db: FluxmailDb, memberId?: string, now?: number): OAuthGrantInfo[];
+export declare function getOAuthGrant(db: FluxmailDb, grantId: string, now?: number): OAuthGrantInfo | null;
+/** Revoke one active grant. Pass memberId to limit the change to that member's grants. */
+export declare function revokeOAuthGrant(db: FluxmailDb, grantId: string, memberId?: string, now?: number): boolean;
+/** Revoke every grant a member approved, for suspension and password changes. */
+export declare function revokeMemberOAuthGrants(db: FluxmailDb | Tx, memberId: string, now?: number): number;
+/** Replace the mailbox narrowing of an active grant. Existing tokens use it on their next request. */
+export declare function updateOAuthGrantAccounts(db: FluxmailDb, grantId: string, accountIds: readonly string[] | null, now?: number): boolean;
+/** Count active grants per member for listings. */
+export declare function countActiveOAuthGrants(db: FluxmailDb, memberId: string, now?: number): number;
+export {};
+//# sourceMappingURL=oauth.d.ts.map

package/dist/storage/oauth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth.d.ts","sourceRoot":"","sources":["../../src/storage/oauth.ts"],"names":[],"mappings":"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"}