handshake-auth 0.1.0 → 0.2.0

package/dist/strategies/twitter-x.d.ts

@@ -0,0 +1,130 @@
+import type { OAuthProfile, AuthResult, HandshakeCallbacks } from '../types.js';
+import { OAuthStrategy } from './oauth-base.js';
+/**
+ * Twitter/X user profile from the /2/users/me endpoint.
+ */
+export interface TwitterXProfile {
+    data: {
+        id: string;
+        name: string;
+        username: string;
+        profile_image_url?: string;
+        description?: string;
+        location?: string;
+        url?: string;
+        verified?: boolean;
+        created_at?: string;
+        public_metrics?: {
+            followers_count: number;
+            following_count: number;
+            tweet_count: number;
+            listed_count: number;
+        };
+    };
+}
+/**
+ * Configuration options for Twitter/X OAuth strategy.
+ */
+export interface TwitterXStrategyOptions {
+    /**
+     * Twitter/X OAuth 2.0 client ID
+     */
+    clientId: string;
+    /**
+     * Twitter/X OAuth 2.0 client secret
+     */
+    clientSecret: string;
+    /**
+     * Your callback URL (must match Twitter Developer Portal configuration)
+     */
+    redirectUri: string;
+    /**
+     * OAuth scopes to request
+     * @default ['tweet.read', 'users.read']
+     */
+    scopes?: string[];
+}
+/**
+ * Twitter/X OAuth 2.0 authentication strategy.
+ *
+ * Uses OAuth 2.0 with PKCE (Proof Key for Code Exchange) as required by
+ * Twitter's API v2.
+ *
+ * Note: Twitter does not provide email addresses through the OAuth API.
+ * The profile will have email set to null.
+ *
+ * @example
+ * ```typescript
+ * const hs = new Handshake({
+ *   findAccount: async (email) => db.accounts.findByEmail(email),
+ *   findOrCreateFromOAuth: async (provider, profile) => {
+ *     // Note: Twitter doesn't provide email, use profile.id for lookup
+ *     let account = await db.accounts.findByProviderId(provider, profile.id);
+ *     if (!account) {
+ *       account = await db.accounts.create({
+ *         name: profile.name,
+ *         providerId: profile.id,
+ *         provider,
+ *         // You may want to prompt user for email separately
+ *       });
+ *     }
+ *     return account;
+ *   },
+ * });
+ *
+ * hs.use(new TwitterXStrategy({
+ *   clientId: process.env.TWITTER_CLIENT_ID!,
+ *   clientSecret: process.env.TWITTER_CLIENT_SECRET!,
+ *   redirectUri: 'http://localhost:3000/auth/twitter/callback',
+ * }));
+ *
+ * // Routes
+ * app.get('/auth/twitter', async (req, res) => {
+ *   const result = await hs.authenticate('twitter-x', req, res, 'redirect');
+ *   if ('redirectUrl' in result) {
+ *     res.redirect(result.redirectUrl);
+ *   }
+ * });
+ *
+ * app.get('/auth/twitter/callback', async (req, res) => {
+ *   const result = await hs.authenticate('twitter-x', req, res, 'callback');
+ *   if (result.account) {
+ *     login(req, result.account);
+ *     res.redirect('/dashboard');
+ *   } else {
+ *     res.status(401).send(result.error);
+ *   }
+ * });
+ * ```
+ */
+export declare class TwitterXStrategy<TAccount> extends OAuthStrategy<TAccount> {
+    private readonly codeVerifierCookieName;
+    constructor(options: TwitterXStrategyOptions);
+    /**
+     * Override authenticate to handle PKCE flow.
+     */
+    authenticate(callbacks: HandshakeCallbacks<TAccount>, ...args: unknown[]): Promise<AuthResult<TAccount>>;
+    /**
+     * Handle redirect with PKCE challenge.
+     */
+    private handleRedirectWithPKCE;
+    /**
+     * Handle callback with PKCE verification.
+     */
+    private handleCallbackWithPKCE;
+    /**
+     * Exchange code for token using PKCE.
+     */
+    private exchangeCodeWithPKCE;
+    /**
+     * Fetch user profile with additional fields.
+     */
+    protected fetchUserProfile(accessToken: string): Promise<OAuthProfile | {
+        error: string;
+    }>;
+    /**
+     * Map Twitter/X profile to standard OAuthProfile.
+     */
+    protected mapProfile(data: unknown, accessToken: string): OAuthProfile;
+}
+//# sourceMappingURL=twitter-x.d.ts.map

package/dist/strategies/twitter-x.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"twitter-x.d.ts","sourceRoot":"","sources":["../../src/strategies/twitter-x.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAChF,OAAO,EAAE,aAAa,EAA2C,MAAM,iBAAiB,CAAC;AAEzF;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE;QACJ,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;QACjB,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,cAAc,CAAC,EAAE;YACf,eAAe,EAAE,MAAM,CAAC;YACxB,eAAe,EAAE,MAAM,CAAC;YACxB,WAAW,EAAE,MAAM,CAAC;YACpB,YAAY,EAAE,MAAM,CAAC;SACtB,CAAC;KACH,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,qBAAa,gBAAgB,CAAC,QAAQ,CAAE,SAAQ,aAAa,CAAC,QAAQ,CAAC;IACrE,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAA2B;gBAEtD,OAAO,EAAE,uBAAuB;IAc5C;;OAEG;IACG,YAAY,CAChB,SAAS,EAAE,kBAAkB,CAAC,QAAQ,CAAC,EACvC,GAAG,IAAI,EAAE,OAAO,EAAE,GACjB,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;IAehC;;OAEG;IACH,OAAO,CAAC,sBAAsB;IA2C9B;;OAEG;YACW,sBAAsB;IAqFpC;;OAEG;YACW,oBAAoB;IA0ClC;;OAEG;cACa,gBAAgB,CAC9B,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,YAAY,GAAG;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IA6B5C;;OAEG;IAEH,SAAS,CAAC,UAAU,CAAC,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,GAAG,YAAY;CAYvE"}

package/dist/strategies/twitter-x.js

@@ -0,0 +1,275 @@
+import { randomBytes, createHash } from 'crypto';
+import { OAuthStrategy } from './oauth-base.js';
+/**
+ * Twitter/X OAuth 2.0 authentication strategy.
+ *
+ * Uses OAuth 2.0 with PKCE (Proof Key for Code Exchange) as required by
+ * Twitter's API v2.
+ *
+ * Note: Twitter does not provide email addresses through the OAuth API.
+ * The profile will have email set to null.
+ *
+ * @example
+ * ```typescript
+ * const hs = new Handshake({
+ *   findAccount: async (email) => db.accounts.findByEmail(email),
+ *   findOrCreateFromOAuth: async (provider, profile) => {
+ *     // Note: Twitter doesn't provide email, use profile.id for lookup
+ *     let account = await db.accounts.findByProviderId(provider, profile.id);
+ *     if (!account) {
+ *       account = await db.accounts.create({
+ *         name: profile.name,
+ *         providerId: profile.id,
+ *         provider,
+ *         // You may want to prompt user for email separately
+ *       });
+ *     }
+ *     return account;
+ *   },
+ * });
+ *
+ * hs.use(new TwitterXStrategy({
+ *   clientId: process.env.TWITTER_CLIENT_ID!,
+ *   clientSecret: process.env.TWITTER_CLIENT_SECRET!,
+ *   redirectUri: 'http://localhost:3000/auth/twitter/callback',
+ * }));
+ *
+ * // Routes
+ * app.get('/auth/twitter', async (req, res) => {
+ *   const result = await hs.authenticate('twitter-x', req, res, 'redirect');
+ *   if ('redirectUrl' in result) {
+ *     res.redirect(result.redirectUrl);
+ *   }
+ * });
+ *
+ * app.get('/auth/twitter/callback', async (req, res) => {
+ *   const result = await hs.authenticate('twitter-x', req, res, 'callback');
+ *   if (result.account) {
+ *     login(req, result.account);
+ *     res.redirect('/dashboard');
+ *   } else {
+ *     res.status(401).send(result.error);
+ *   }
+ * });
+ * ```
+ */
+export class TwitterXStrategy extends OAuthStrategy {
+    codeVerifierCookieName = 'twitter_code_verifier';
+    constructor(options) {
+        super({
+            name: 'twitter-x',
+            clientId: options.clientId,
+            clientSecret: options.clientSecret,
+            redirectUri: options.redirectUri,
+            authorizeUrl: 'https://twitter.com/i/oauth2/authorize',
+            tokenUrl: 'https://api.twitter.com/2/oauth2/token',
+            userInfoUrl: 'https://api.twitter.com/2/users/me',
+            scopes: options.scopes ?? ['tweet.read', 'users.read'],
+            stateCookieName: 'twitter_oauth_state',
+        });
+    }
+    /**
+     * Override authenticate to handle PKCE flow.
+     */
+    async authenticate(callbacks, ...args) {
+        const [req, res, phase] = args;
+        if (phase === 'redirect') {
+            return this.handleRedirectWithPKCE(req, res);
+        }
+        else if (phase === 'callback') {
+            return this.handleCallbackWithPKCE(callbacks, req, res);
+        }
+        else {
+            return {
+                account: null,
+                error: `Invalid OAuth phase: ${phase}. Use 'redirect' or 'callback'`,
+            };
+        }
+    }
+    /**
+     * Handle redirect with PKCE challenge.
+     */
+    handleRedirectWithPKCE(_req, res) {
+        // Generate PKCE code verifier and challenge
+        const codeVerifier = randomBytes(32).toString('base64url');
+        const codeChallenge = createHash('sha256')
+            .update(codeVerifier)
+            .digest('base64url');
+        // Generate state for CSRF protection
+        const state = randomBytes(32).toString('hex');
+        // Store state and code verifier in cookies
+        const cookieOptions = {
+            httpOnly: true,
+            secure: process.env.NODE_ENV === 'production',
+            sameSite: 'lax',
+            maxAge: 10 * 60 * 1000, // 10 minutes
+        };
+        res.cookie(this.stateCookieName, state, cookieOptions);
+        res.cookie(this.codeVerifierCookieName, codeVerifier, cookieOptions);
+        // Build authorization URL with PKCE
+        const params = new URLSearchParams({
+            client_id: this.clientId,
+            redirect_uri: this.redirectUri,
+            response_type: 'code',
+            scope: this.scopes.join(' '),
+            state,
+            code_challenge: codeChallenge,
+            code_challenge_method: 'S256',
+        });
+        const redirectUrl = `${this.authorizeUrl}?${params.toString()}`;
+        return {
+            account: null,
+            redirectUrl,
+        };
+    }
+    /**
+     * Handle callback with PKCE verification.
+     */
+    async handleCallbackWithPKCE(callbacks, req, res) {
+        // Get state, code, and verifier
+        const { state: returnedState, code, error, error_description } = req.query;
+        // Check for OAuth error response
+        if (error) {
+            return {
+                account: null,
+                error: error_description || error,
+            };
+        }
+        // Verify state
+        const storedState = req.cookies?.[this.stateCookieName];
+        const codeVerifier = req.cookies?.[this.codeVerifierCookieName];
+        // Clear cookies
+        res.clearCookie(this.stateCookieName);
+        res.clearCookie(this.codeVerifierCookieName);
+        if (!storedState || storedState !== returnedState) {
+            return {
+                account: null,
+                error: 'Invalid OAuth state. Possible CSRF attack or expired session.',
+            };
+        }
+        if (!code) {
+            return {
+                account: null,
+                error: 'No authorization code received',
+            };
+        }
+        if (!codeVerifier) {
+            return {
+                account: null,
+                error: 'Missing PKCE code verifier. Session may have expired.',
+            };
+        }
+        // Exchange code for token with PKCE
+        const tokenResult = await this.exchangeCodeWithPKCE(code, codeVerifier);
+        if ('error' in tokenResult) {
+            return {
+                account: null,
+                error: tokenResult.error,
+            };
+        }
+        // Fetch user profile
+        const profileResult = await this.fetchUserProfile(tokenResult.access_token);
+        if ('error' in profileResult) {
+            return {
+                account: null,
+                error: profileResult.error,
+            };
+        }
+        // Check for required callback
+        if (!callbacks.findOrCreateFromOAuth) {
+            return {
+                account: null,
+                error: 'findOrCreateFromOAuth callback is required for OAuth strategies',
+            };
+        }
+        // Let the application handle account creation/lookup
+        const account = await callbacks.findOrCreateFromOAuth(this.name, profileResult);
+        return {
+            account,
+            strategy: this.name,
+        };
+    }
+    /**
+     * Exchange code for token using PKCE.
+     */
+    async exchangeCodeWithPKCE(code, codeVerifier) {
+        try {
+            // Twitter requires Basic auth for token exchange
+            const credentials = Buffer.from(`${this.clientId}:${this.clientSecret}`).toString('base64');
+            const params = new URLSearchParams({
+                code,
+                grant_type: 'authorization_code',
+                redirect_uri: this.redirectUri,
+                code_verifier: codeVerifier,
+            });
+            const response = await fetch(this.tokenUrl, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/x-www-form-urlencoded',
+                    Authorization: `Basic ${credentials}`,
+                    Accept: 'application/json',
+                },
+                body: params.toString(),
+            });
+            if (!response.ok) {
+                const errorData = await response.json().catch(() => ({}));
+                return {
+                    error: errorData.error_description ||
+                        errorData.error ||
+                        `Token exchange failed: ${response.status}`,
+                };
+            }
+            return (await response.json());
+        }
+        catch (err) {
+            return {
+                error: `Token exchange failed: ${err instanceof Error ? err.message : 'Unknown error'}`,
+            };
+        }
+    }
+    /**
+     * Fetch user profile with additional fields.
+     */
+    async fetchUserProfile(accessToken) {
+        try {
+            // Request additional user fields
+            const params = new URLSearchParams({
+                'user.fields': 'id,name,username,profile_image_url,description',
+            });
+            const response = await fetch(`${this.userInfoUrl}?${params.toString()}`, {
+                headers: {
+                    Authorization: `Bearer ${accessToken}`,
+                    Accept: 'application/json',
+                },
+            });
+            if (!response.ok) {
+                return {
+                    error: `Failed to fetch user profile: ${response.status}`,
+                };
+            }
+            const data = await response.json();
+            return this.mapProfile(data, accessToken);
+        }
+        catch (err) {
+            return {
+                error: `Failed to fetch user profile: ${err instanceof Error ? err.message : 'Unknown error'}`,
+            };
+        }
+    }
+    /**
+     * Map Twitter/X profile to standard OAuthProfile.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    mapProfile(data, accessToken) {
+        const response = data;
+        const profile = response.data;
+        return {
+            id: profile.id,
+            email: null, // Twitter doesn't provide email through OAuth
+            name: profile.name,
+            picture: profile.profile_image_url ?? null,
+            raw: profile,
+        };
+    }
+}
+//# sourceMappingURL=twitter-x.js.map

package/dist/strategies/twitter-x.js.map

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

package/dist/strategies/username-password.d.ts

@@ -0,0 +1,38 @@
+import type { AuthResult, Strategy, HandshakeCallbacks } from '../types.js';
+/**
+ * Username/Password authentication strategy.
+ *
+ * Authenticates users with an identifier (e.g., email, username) and password.
+ * Uses the findAccount and verifyPassword callbacks from Handshake.
+ *
+ * @example
+ * ```typescript
+ * const hs = new Handshake({
+ *   findAccount: async (email) => db.accounts.findByEmail(email),
+ *   verifyPassword: async (account, password) => {
+ *     return bcrypt.compare(password, account.passwordHash);
+ *   },
+ * });
+ *
+ * hs.use(new UsernamePasswordStrategy());
+ *
+ * // In your login route
+ * const result = await hs.authenticate('username-password', email, password);
+ * if (result.account) {
+ *   login(req, result.account);
+ * }
+ * ```
+ */
+export declare class UsernamePasswordStrategy<TAccount> implements Strategy<TAccount> {
+    readonly name = "username-password";
+    /**
+     * Authenticate with identifier and password.
+     *
+     * @param callbacks - Handshake callbacks (findAccount, verifyPassword)
+     * @param identifier - The account identifier (e.g., email, username)
+     * @param password - The password to verify
+     * @returns Authentication result with account or error
+     */
+    authenticate(callbacks: HandshakeCallbacks<TAccount>, ...args: unknown[]): Promise<AuthResult<TAccount>>;
+}
+//# sourceMappingURL=username-password.d.ts.map

package/dist/strategies/username-password.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"username-password.d.ts","sourceRoot":"","sources":["../../src/strategies/username-password.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAE5E;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,wBAAwB,CAAC,QAAQ,CAAE,YAAW,QAAQ,CAAC,QAAQ,CAAC;IAC3E,QAAQ,CAAC,IAAI,uBAAuB;IAEpC;;;;;;;OAOG;IACG,YAAY,CAChB,SAAS,EAAE,kBAAkB,CAAC,QAAQ,CAAC,EACvC,GAAG,IAAI,EAAE,OAAO,EAAE,GACjB,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;CAgCjC"}

package/dist/strategies/username-password.js

@@ -0,0 +1,61 @@
+/**
+ * Username/Password authentication strategy.
+ *
+ * Authenticates users with an identifier (e.g., email, username) and password.
+ * Uses the findAccount and verifyPassword callbacks from Handshake.
+ *
+ * @example
+ * ```typescript
+ * const hs = new Handshake({
+ *   findAccount: async (email) => db.accounts.findByEmail(email),
+ *   verifyPassword: async (account, password) => {
+ *     return bcrypt.compare(password, account.passwordHash);
+ *   },
+ * });
+ *
+ * hs.use(new UsernamePasswordStrategy());
+ *
+ * // In your login route
+ * const result = await hs.authenticate('username-password', email, password);
+ * if (result.account) {
+ *   login(req, result.account);
+ * }
+ * ```
+ */
+export class UsernamePasswordStrategy {
+    name = 'username-password';
+    /**
+     * Authenticate with identifier and password.
+     *
+     * @param callbacks - Handshake callbacks (findAccount, verifyPassword)
+     * @param identifier - The account identifier (e.g., email, username)
+     * @param password - The password to verify
+     * @returns Authentication result with account or error
+     */
+    async authenticate(callbacks, ...args) {
+        const [identifier, password] = args;
+        if (!identifier || !password) {
+            return { account: null, error: 'Identifier and password are required' };
+        }
+        if (!callbacks.verifyPassword) {
+            return { account: null, error: 'verifyPassword callback is required for username-password strategy' };
+        }
+        // Find the account
+        const account = await callbacks.findAccount(identifier);
+        // Always call verifyPassword even if account is null to prevent timing attacks.
+        // The verifyPassword callback should handle null accounts appropriately
+        // (e.g., by doing a dummy comparison that takes the same time).
+        // However, since the callback signature requires an account, we'll check first
+        // and rely on the overall operation timing being similar.
+        if (!account) {
+            return { account: null, error: 'Invalid credentials' };
+        }
+        // Verify the password
+        const isValid = await callbacks.verifyPassword(account, password);
+        if (!isValid) {
+            return { account: null, error: 'Invalid credentials' };
+        }
+        return { account, strategy: this.name };
+    }
+}
+//# sourceMappingURL=username-password.js.map

package/dist/strategies/username-password.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"username-password.js","sourceRoot":"","sources":["../../src/strategies/username-password.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,OAAO,wBAAwB;IAC1B,IAAI,GAAG,mBAAmB,CAAC;IAEpC;;;;;;;OAOG;IACH,KAAK,CAAC,YAAY,CAChB,SAAuC,EACvC,GAAG,IAAe;QAElB,MAAM,CAAC,UAAU,EAAE,QAAQ,CAAC,GAAG,IAAwB,CAAC;QAExD,IAAI,CAAC,UAAU,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC7B,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,sCAAsC,EAAE,CAAC;QAC1E,CAAC;QAED,IAAI,CAAC,SAAS,CAAC,cAAc,EAAE,CAAC;YAC9B,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,oEAAoE,EAAE,CAAC;QACxG,CAAC;QAED,mBAAmB;QACnB,MAAM,OAAO,GAAG,MAAM,SAAS,CAAC,WAAW,CAAC,UAAU,CAAC,CAAC;QAExD,gFAAgF;QAChF,wEAAwE;QACxE,gEAAgE;QAChE,+EAA+E;QAC/E,0DAA0D;QAC1D,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,qBAAqB,EAAE,CAAC;QACzD,CAAC;QAED,sBAAsB;QACtB,MAAM,OAAO,GAAG,MAAM,SAAS,CAAC,cAAc,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QAElE,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,qBAAqB,EAAE,CAAC;QACzD,CAAC;QAED,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC;IAC1C,CAAC;CACF"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "handshake-auth",
   "description": "Lightweight, storage-agnostic authentication for Express.js",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -39,7 +39,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/chilts/handshake-auth.git"
+    "url": "https://codeberg.org/chilts/handshake-auth.git"
   },
   "author": {
     "name": "Andrew Chilton",