feat(oauth): add the state binding to the start response and callback request

.changeset/oauth-state-binding.md

@@ -0,0 +1,8 @@
+---
+'@seamless-auth/types': minor
+---
+
+Add `binding` to the OAuth start response and the callback request. The auth server returns a
+random `binding` from `/oauth/:providerId/start` and checks it on `/oauth/:providerId/callback`,
+so a `state` can only be finished by the client that started the sign-in. Both fields are
+optional in the schemas so a client can still parse a response from an older auth server.

src/schemas/oauth/schema.test.ts

@@ -1,8 +1,10 @@
 import { describe, it, expect } from 'vitest';
 import {
+  FinishOAuthLoginRequestSchema,
   OAuthLoginErrorResponseSchema,
   OAuthLoginSuccessResponseSchema,
   StartOAuthLoginRequestSchema,
+  StartOAuthLoginResponseSchema,
 } from './schema.js';
 
 describe('StartOAuthLoginRequestSchema', () => {
@@ -93,3 +95,33 @@ describe('nextStep on the other sign-ins', () => {
     ).toBe('enroll_passkey');
   });
 });
+
+describe('StartOAuthLoginResponseSchema', () => {
+  const base = {
+    provider: { id: 'google', name: 'Google', scopes: ['openid'] },
+    state: 'payload.signature',
+    authorizationUrl: 'https://accounts.example.com/authorize',
+  };
+
+  it('carries the binding', () => {
+    expect(StartOAuthLoginResponseSchema.parse({ ...base, binding: 'b1' }).binding).toBe('b1');
+  });
+
+  it('parses a response from a server that sends no binding', () => {
+    expect(StartOAuthLoginResponseSchema.parse(base).binding).toBeUndefined();
+  });
+});
+
+describe('FinishOAuthLoginRequestSchema', () => {
+  it('accepts a binding', () => {
+    expect(
+      FinishOAuthLoginRequestSchema.parse({ code: 'c', state: 's', binding: 'b1' }).binding,
+    ).toBe('b1');
+  });
+
+  it('refuses an empty binding', () => {
+    expect(() =>
+      FinishOAuthLoginRequestSchema.parse({ code: 'c', state: 's', binding: ' ' }),
+    ).toThrow();
+  });
+});

src/schemas/oauth/schema.ts

@@ -35,13 +35,21 @@ export const StartOAuthLoginResponseSchema = z.object({
   provider: PublicOAuthProviderSchema,
   state: z.string(),
   authorizationUrl: z.url(),
+  /**
+   * Binds `state` to the client that started the sign-in. The client keeps it and sends
+   * it back with the callback; it never goes to the provider. Optional only so a client
+   * can parse a response from an auth server that predates it.
+   */
+  binding: z.string().optional(),
 });
 
 export type StartOAuthLoginResponse = z.infer<typeof StartOAuthLoginResponseSchema>;
 
 export const FinishOAuthLoginRequestSchema = z.object({
   code: z.string().trim().min(1),
   state: z.string().trim().min(1),
+  /** The `binding` the start response returned to this client. */
+  binding: z.string().trim().min(1).optional(),
 });
 
 export type FinishOAuthLoginRequest = z.infer<typeof FinishOAuthLoginRequestSchema>;