cauthy-auth 0.12.0 → 0.14.0

package/README.md

@@ -123,6 +123,14 @@ const who = await verifyToken(request)   // throws CauthyTokenError: answer 401
 who.userId, who.tenantId, who.roles
 ```
 
+An MCP server (or an API) that AI agents use as one of your people: Claude, Cursor and others find Cauthy from it, the person signs in and allows the agent, and the token works on that server alone.
+
+```ts
+import { mcpAuth } from 'cauthy-auth/mcp'
+const auth = mcpAuth({ resource: 'https://mcp.example.com/mcp', scopes: ['books:read'] })
+app.use(auth.middleware())                    // or auth.protect(handler) for Request/Response
+```
+
 The full guide is in Cauthy's documentation, under "Auth SDK".
 
 ## License

package/dist/client.d.mts

@@ -93,6 +93,13 @@ interface AuthMethods {
      * page that cannot, or a browser that refuses to here, sends the person.
      */
     passkeyOnCauthy: boolean;
+    /**
+     * The workspace's Cloudflare Turnstile site key, when it asks for the
+     * challenge: signing in, creating an account, and asking for a sign-in link
+     * or a new password then take its answer (`captchaToken`). The ready-made
+     * forms show it themselves.
+     */
+    captchaSiteKey?: string;
 }
 /** A passkey of the signed-in account. Moments are UTC. */
 interface Passkey {
@@ -114,6 +121,26 @@ interface Account {
     mfaEnabled: boolean;
 }
 /** Somewhere the person is signed in. Moments are UTC. */
+/** An AI agent the person allowed to act for them on one of the workspace's servers. */
+interface ConnectedAgent {
+    id: string;
+    /** The name the agent gave itself (Claude, Cursor…): not checked by anyone. */
+    name: string;
+    /** Where the agent receives its access: the one thing about it that is sure. */
+    redirectHost: string;
+    resource: {
+        name: string;
+        uri: string;
+    };
+    /** What the person allowed it, in their words. */
+    scopes: {
+        name: string;
+        description: string;
+    }[];
+    /** UTC, ISO 8601. */
+    connectedAt: string;
+    lastUsedAt: string;
+}
 interface AccountSession {
     /** "Mac · Chrome", or "" when the browser did not say. */
     device: string;
@@ -134,6 +161,17 @@ interface LinkedIdentity {
     /** When it was linked, in UTC (ISO 8601). */
     linkedAt: string;
 }
+/** How an account takes its second step. */
+interface SecondStep {
+    totp: boolean;
+    /** The phone codes are sent to, masked (`+57 ••• ••• 4567`). */
+    phone: {
+        number: string;
+        channel: string;
+    } | null;
+    /** The ways the workspace sends codes to phones. */
+    phoneChannels: string[];
+}
 interface AccountClient {
     /** The account, or null when nobody is signed in. */
     get(): Promise<Account | null>;
@@ -172,6 +210,30 @@ interface AccountClient {
         }): Promise<AuthResult<'renewed', {
             recoveryCodes: string[];
         }>>;
+        /**
+         * How the account takes its second step: an authenticator app, a phone
+         * (masked), and the ways the workspace sends codes to phones (`sms`,
+         * `whatsapp`; none when it has no Twilio account for it).
+         */
+        factors(): Promise<SecondStep | null>;
+        /** Adds a phone as the second step: a code is sent to it, for `verifyPhone`. */
+        addPhone(form: {
+            phone: string;
+            channel: 'sms' | 'whatsapp';
+            password: string;
+        }): Promise<AuthResult<'sent', {
+            sentTo: string;
+            channel: string;
+        }>>;
+        /** Proves the phone with the code it received. `recoveryCodes` come with a first second step, shown this once. */
+        verifyPhone(form: {
+            code: string;
+        }): Promise<AuthResult<'enabled', {
+            recoveryCodes: string[];
+        }>>;
+        removePhone(form: {
+            password: string;
+        }): Promise<AuthResult<'removed'>>;
     };
     /**
      * Asks to sign in with another address. Nothing changes yet: the new address
@@ -205,6 +267,12 @@ interface AccountClient {
     sessions(): Promise<AccountSession[]>;
     /** Signs the account out everywhere, here too. */
     signOutEverywhere(): Promise<AuthResult<'signed_out'>>;
+    /** The AI agents the person connected. */
+    agents(): Promise<ConnectedAgent[]>;
+    /** Disconnects an agent: it loses its access within minutes. */
+    disconnectAgent(id: string): Promise<AuthResult<'disconnected', {
+        id: string;
+    }>>;
     /** The account's passkeys. */
     passkeys(): Promise<Passkey[]>;
     /**
@@ -228,6 +296,7 @@ interface AuthClient {
         email(form: {
             email: string;
             password: string;
+            captchaToken?: string;
         }): Promise<AuthResult<'signed_in', {
             session: PublicSession;
         }> | AuthResult<'mfa_required'>>;
@@ -237,9 +306,23 @@ interface AuthClient {
         }): Promise<AuthResult<'signed_in', {
             session: PublicSession;
         }>>;
+        /** While the second step is asked for: whether the account has an authenticator app, and the phone (masked) a code can be sent to. */
+        mfaMethods(): Promise<AuthResult<'ok', {
+            totp: boolean;
+            phone: {
+                number: string;
+                channel: string;
+            } | null;
+        }>>;
+        /** Sends a code to the account's phone, by SMS or WhatsApp; `mfa` takes it. A few per sign-in. */
+        mfaSendCode(): Promise<AuthResult<'sent', {
+            sentTo: string;
+            channel: string;
+        }>>;
         /** Mails a link that signs the person in. The answer is the same whether or not the address has an account. */
         magicLink(form: {
             email: string;
+            captchaToken?: string;
         }): Promise<AuthResult<'sent'>>;
         /** Signs in with the token the mailed link opened the page with (`ml_token`). */
         magicLinkVerify(form: {
@@ -315,6 +398,7 @@ interface AuthClient {
             email: string;
             password: string;
             name?: string;
+            captchaToken?: string;
         }): Promise<AuthResult<'signed_in', {
             session: PublicSession;
         }> | AuthResult<'verification_required', {
@@ -324,6 +408,7 @@ interface AuthClient {
     /** Mails a link to choose a new password. The answer is the same whether or not the address has an account. */
     forgotPassword(form: {
         email: string;
+        captchaToken?: string;
     }): Promise<AuthResult<'sent'>>;
     /** Sets the new password, with the token the mailed link opened the page with (`token`). */
     resetPassword(form: {
@@ -360,4 +445,4 @@ interface AuthClientOptions {
 }
 declare function createAuthClient(options?: AuthClientOptions): AuthClient;
 
-export { type Account, type AccountClient, type AccountSession, type AuthClient, type AuthClientOptions, type AuthError, AuthField, type AuthMethods, type AuthResult, type LinkedIdentity, type Passkey, type SessionState, type SessionStore, type SessionStoreOptions, canAutofillPasskeys, canUsePasskeys, createAuthClient, createSessionStore };
+export { type Account, type AccountClient, type AccountSession, type AuthClient, type AuthClientOptions, type AuthError, AuthField, type AuthMethods, type AuthResult, type ConnectedAgent, type LinkedIdentity, type Passkey, type SecondStep, type SessionState, type SessionStore, type SessionStoreOptions, canAutofillPasskeys, canUsePasskeys, createAuthClient, createSessionStore };

package/dist/client.d.ts

@@ -93,6 +93,13 @@ interface AuthMethods {
      * page that cannot, or a browser that refuses to here, sends the person.
      */
     passkeyOnCauthy: boolean;
+    /**
+     * The workspace's Cloudflare Turnstile site key, when it asks for the
+     * challenge: signing in, creating an account, and asking for a sign-in link
+     * or a new password then take its answer (`captchaToken`). The ready-made
+     * forms show it themselves.
+     */
+    captchaSiteKey?: string;
 }
 /** A passkey of the signed-in account. Moments are UTC. */
 interface Passkey {
@@ -114,6 +121,26 @@ interface Account {
     mfaEnabled: boolean;
 }
 /** Somewhere the person is signed in. Moments are UTC. */
+/** An AI agent the person allowed to act for them on one of the workspace's servers. */
+interface ConnectedAgent {
+    id: string;
+    /** The name the agent gave itself (Claude, Cursor…): not checked by anyone. */
+    name: string;
+    /** Where the agent receives its access: the one thing about it that is sure. */
+    redirectHost: string;
+    resource: {
+        name: string;
+        uri: string;
+    };
+    /** What the person allowed it, in their words. */
+    scopes: {
+        name: string;
+        description: string;
+    }[];
+    /** UTC, ISO 8601. */
+    connectedAt: string;
+    lastUsedAt: string;
+}
 interface AccountSession {
     /** "Mac · Chrome", or "" when the browser did not say. */
     device: string;
@@ -134,6 +161,17 @@ interface LinkedIdentity {
     /** When it was linked, in UTC (ISO 8601). */
     linkedAt: string;
 }
+/** How an account takes its second step. */
+interface SecondStep {
+    totp: boolean;
+    /** The phone codes are sent to, masked (`+57 ••• ••• 4567`). */
+    phone: {
+        number: string;
+        channel: string;
+    } | null;
+    /** The ways the workspace sends codes to phones. */
+    phoneChannels: string[];
+}
 interface AccountClient {
     /** The account, or null when nobody is signed in. */
     get(): Promise<Account | null>;
@@ -172,6 +210,30 @@ interface AccountClient {
         }): Promise<AuthResult<'renewed', {
             recoveryCodes: string[];
         }>>;
+        /**
+         * How the account takes its second step: an authenticator app, a phone
+         * (masked), and the ways the workspace sends codes to phones (`sms`,
+         * `whatsapp`; none when it has no Twilio account for it).
+         */
+        factors(): Promise<SecondStep | null>;
+        /** Adds a phone as the second step: a code is sent to it, for `verifyPhone`. */
+        addPhone(form: {
+            phone: string;
+            channel: 'sms' | 'whatsapp';
+            password: string;
+        }): Promise<AuthResult<'sent', {
+            sentTo: string;
+            channel: string;
+        }>>;
+        /** Proves the phone with the code it received. `recoveryCodes` come with a first second step, shown this once. */
+        verifyPhone(form: {
+            code: string;
+        }): Promise<AuthResult<'enabled', {
+            recoveryCodes: string[];
+        }>>;
+        removePhone(form: {
+            password: string;
+        }): Promise<AuthResult<'removed'>>;
     };
     /**
      * Asks to sign in with another address. Nothing changes yet: the new address
@@ -205,6 +267,12 @@ interface AccountClient {
     sessions(): Promise<AccountSession[]>;
     /** Signs the account out everywhere, here too. */
     signOutEverywhere(): Promise<AuthResult<'signed_out'>>;
+    /** The AI agents the person connected. */
+    agents(): Promise<ConnectedAgent[]>;
+    /** Disconnects an agent: it loses its access within minutes. */
+    disconnectAgent(id: string): Promise<AuthResult<'disconnected', {
+        id: string;
+    }>>;
     /** The account's passkeys. */
     passkeys(): Promise<Passkey[]>;
     /**
@@ -228,6 +296,7 @@ interface AuthClient {
         email(form: {
             email: string;
             password: string;
+            captchaToken?: string;
         }): Promise<AuthResult<'signed_in', {
             session: PublicSession;
         }> | AuthResult<'mfa_required'>>;
@@ -237,9 +306,23 @@ interface AuthClient {
         }): Promise<AuthResult<'signed_in', {
             session: PublicSession;
         }>>;
+        /** While the second step is asked for: whether the account has an authenticator app, and the phone (masked) a code can be sent to. */
+        mfaMethods(): Promise<AuthResult<'ok', {
+            totp: boolean;
+            phone: {
+                number: string;
+                channel: string;
+            } | null;
+        }>>;
+        /** Sends a code to the account's phone, by SMS or WhatsApp; `mfa` takes it. A few per sign-in. */
+        mfaSendCode(): Promise<AuthResult<'sent', {
+            sentTo: string;
+            channel: string;
+        }>>;
         /** Mails a link that signs the person in. The answer is the same whether or not the address has an account. */
         magicLink(form: {
             email: string;
+            captchaToken?: string;
         }): Promise<AuthResult<'sent'>>;
         /** Signs in with the token the mailed link opened the page with (`ml_token`). */
         magicLinkVerify(form: {
@@ -315,6 +398,7 @@ interface AuthClient {
             email: string;
             password: string;
             name?: string;
+            captchaToken?: string;
         }): Promise<AuthResult<'signed_in', {
             session: PublicSession;
         }> | AuthResult<'verification_required', {
@@ -324,6 +408,7 @@ interface AuthClient {
     /** Mails a link to choose a new password. The answer is the same whether or not the address has an account. */
     forgotPassword(form: {
         email: string;
+        captchaToken?: string;
     }): Promise<AuthResult<'sent'>>;
     /** Sets the new password, with the token the mailed link opened the page with (`token`). */
     resetPassword(form: {
@@ -360,4 +445,4 @@ interface AuthClientOptions {
 }
 declare function createAuthClient(options?: AuthClientOptions): AuthClient;
 
-export { type Account, type AccountClient, type AccountSession, type AuthClient, type AuthClientOptions, type AuthError, AuthField, type AuthMethods, type AuthResult, type LinkedIdentity, type Passkey, type SessionState, type SessionStore, type SessionStoreOptions, canAutofillPasskeys, canUsePasskeys, createAuthClient, createSessionStore };
+export { type Account, type AccountClient, type AccountSession, type AuthClient, type AuthClientOptions, type AuthError, AuthField, type AuthMethods, type AuthResult, type ConnectedAgent, type LinkedIdentity, type Passkey, type SecondStep, type SessionState, type SessionStore, type SessionStoreOptions, canAutofillPasskeys, canUsePasskeys, createAuthClient, createSessionStore };

package/dist/client.js

@@ -317,13 +317,13 @@ function createAuthClient(options = {}) {
     const said = typeof options.locale === "function" ? options.locale() : options.locale;
     return (said ?? (typeof document === "undefined" ? "" : document.documentElement?.lang) ?? "").trim();
   };
-  async function post(path, form, bad) {
+  async function post(path, form, bad, captchaToken) {
     if (bad) return { ok: false, error: { code: bad.code, message: bad.message, field: bad.field } };
     try {
       const res = await doFetch(`${base}${path}`, {
         method: "POST",
         credentials: "same-origin",
-        headers: { "content-type": "application/json", accept: "application/json", ...locale() ? { "x-cauthy-locale": locale() } : {} },
+        headers: { "content-type": "application/json", accept: "application/json", ...locale() ? { "x-cauthy-locale": locale() } : {}, ...captchaToken ? { "x-cauthy-captcha": captchaToken } : {} },
         body: JSON.stringify(form)
       });
       const body = await res.json().catch(() => null);
@@ -375,9 +375,11 @@ function createAuthClient(options = {}) {
   }
   return {
     signIn: {
-      email: (f) => post("/sign-in/email", { email: f.email, password: f.password }, firstProblem(checkEmail(f.email), checkPassword(f.password))),
+      email: (f) => post("/sign-in/email", { email: f.email, password: f.password }, firstProblem(checkEmail(f.email), checkPassword(f.password)), f.captchaToken),
       mfa: (f) => post("/sign-in/mfa", { code: f.code }, checkCode(f.code)),
-      magicLink: (f) => post("/sign-in/magic-link", { email: f.email }, checkEmail(f.email)),
+      mfaMethods: () => post("/sign-in/mfa/methods", {}, null),
+      mfaSendCode: () => post("/sign-in/mfa/send", {}, null),
+      magicLink: (f) => post("/sign-in/magic-link", { email: f.email }, checkEmail(f.email), f.captchaToken),
       magicLinkVerify: (f) => post("/sign-in/magic-link/verify", { token: f.token }, null),
       emailCode: (f) => post("/sign-in/email-code", { code: f.code }, checkCode(f.code)),
       passkeyUrl,
@@ -458,9 +460,9 @@ function createAuthClient(options = {}) {
       }
     },
     signUp: {
-      email: (f) => post("/sign-up/email", { email: f.email, password: f.password, name: f.name }, firstProblem(checkName(f.name), checkEmail(f.email), checkNewPassword(f.password)))
+      email: (f) => post("/sign-up/email", { email: f.email, password: f.password, name: f.name }, firstProblem(checkName(f.name), checkEmail(f.email), checkNewPassword(f.password)), f.captchaToken)
     },
-    forgotPassword: (f) => post("/forgot-password", { email: f.email }, checkEmail(f.email)),
+    forgotPassword: (f) => post("/forgot-password", { email: f.email }, checkEmail(f.email), f.captchaToken),
     resetPassword: (f) => post("/reset-password", { token: f.token, password: f.password }, checkNewPassword(f.password)),
     verifyEmail: (f) => post("/verify-email", { token: f.token }, null),
     signOut: () => post("/sign-out", {}, null),
@@ -478,7 +480,14 @@ function createAuthClient(options = {}) {
         setup: (f) => post("/me/mfa/setup", { password: f.password }, null),
         verify: (f) => post("/me/mfa/verify", { code: f.code }, checkCode(f.code)),
         disable: (f) => post("/me/mfa/disable", { password: f.password }, null),
-        recoveryCodes: (f) => post("/me/mfa/recovery-codes", { password: f.password }, null)
+        recoveryCodes: (f) => post("/me/mfa/recovery-codes", { password: f.password }, null),
+        async factors() {
+          const body = await read("/me/mfa/factors");
+          return body && typeof body.totp === "boolean" ? body : null;
+        },
+        addPhone: (f) => post("/me/mfa/phone", { phone: f.phone, channel: f.channel, password: f.password }, null),
+        verifyPhone: (f) => post("/me/mfa/phone/verify", { code: f.code }, checkCode(f.code)),
+        removePhone: (f) => post("/me/mfa/phone/remove", { password: f.password }, null)
       },
       changeEmail: (f) => post("/me/email", { email: f.email, password: f.password }, checkEmail(f.email)),
       async identities() {
@@ -495,6 +504,11 @@ function createAuthClient(options = {}) {
         return body && Array.isArray(body.sessions) ? body.sessions : [];
       },
       signOutEverywhere: () => post("/me/sessions/end", {}, null),
+      async agents() {
+        const body = await read("/me/agents");
+        return body && Array.isArray(body.agents) ? body.agents : [];
+      },
+      disconnectAgent: (id) => post("/me/agents/disconnect", { id }, null),
       async passkeys() {
         const body = await read("/me/passkeys");
         return body && Array.isArray(body.passkeys) ? body.passkeys : [];