@ankhorage/contracts 2.0.0 → 3.0.0

package/src/auth-oauth.test.ts

@@ -1,12 +1,58 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
 import { describe, expect, it } from 'bun:test';
 
 import {
+  AUTH_OAUTH_CANCELLATION_REASONS,
+  AUTH_OAUTH_ERROR_CODES,
   AUTH_OAUTH_PROVIDER_IDS,
   type AuthAdapter,
   type AuthOAuthConfig,
+  type AuthSession,
   type AuthSpec,
 } from './index';
 
+const session: AuthSession = {
+  accessToken: 'access-token',
+  refreshToken: 'refresh-token',
+  user: {
+    id: 'user-1',
+    email: 'person@example.com',
+  },
+};
+
+function createBaseAdapter(): Omit<AuthAdapter, 'oauth'> {
+  return {
+    capabilities: {
+      signInIdentifiers: ['email'],
+      supportsSignUp: true,
+      supportsPasswordReset: true,
+      supportsOtp: true,
+      supportsSessionRefresh: true,
+    },
+    signIn() {
+      return Promise.resolve({
+        ok: false,
+        error: { code: 'unsupported', message: 'Password sign-in is not implemented.' },
+      });
+    },
+    signUp() {
+      return Promise.resolve({
+        ok: false,
+        error: { code: 'unsupported', message: 'Sign-up is not implemented.' },
+      });
+    },
+    signOut() {
+      return Promise.resolve({ ok: true });
+    },
+    getSession() {
+      return Promise.resolve({ ok: true, data: null });
+    },
+  };
+}
+
 describe('OAuth auth contracts', () => {
   it('accepts provider-neutral OAuth provider config on auth specs', () => {
     const oauth: AuthOAuthConfig = {
@@ -27,7 +73,6 @@ describe('OAuth auth contracts', () => {
           id: 'custom-sso',
           label: 'Custom SSO',
           enabled: false,
-          redirectTo: '/auth/custom/callback',
           queryParams: {
             prompt: 'select_account',
           },
@@ -38,7 +83,6 @@ describe('OAuth auth contracts', () => {
     const auth: AuthSpec = {
       scope: 'global',
       provider: 'supabase',
-      authorization: { kind: 'RBAC', engine: 'native' },
       oauth,
     };
 
@@ -48,56 +92,157 @@ describe('OAuth auth contracts', () => {
     expect(auth.oauth?.providers[1]?.enabled).toBe(false);
   });
 
-  it('accepts optional OAuth adapter capabilities and redirect flow methods', async () => {
+  it('advertises OAuth only through one complete start and completion capability', async () => {
     const adapter: AuthAdapter = {
-      capabilities: {
-        signInIdentifiers: ['email'],
-        supportsSignUp: true,
-        supportsPasswordReset: true,
-        supportsOtp: true,
-        supportsSessionRefresh: true,
-        supportsOAuth: true,
-        oauthProviders: ['google', 'custom-sso'],
-      },
-      signIn() {
-        return Promise.resolve({
-          ok: false,
-          error: { code: 'unsupported', message: 'Password sign-in is not implemented.' },
-        });
-      },
-      signUp() {
-        return Promise.resolve({
-          ok: false,
-          error: { code: 'unsupported', message: 'Sign-up is not implemented.' },
-        });
-      },
-      signOut() {
-        return Promise.resolve({ ok: true });
+      ...createBaseAdapter(),
+      oauth: {
+        capabilities: {
+          providers: ['google', 'custom-sso'],
+        },
+        startAuthorization(input) {
+          return Promise.resolve({
+            ok: true,
+            data: {
+              attemptId: 'oauth-attempt-1',
+              provider: input.provider,
+              authorizationUrl: `https://auth.example.com/oauth/${input.provider}`,
+              redirectUri: input.redirectUri,
+            },
+          });
+        },
+        completeAuthorization(input) {
+          if (input.response.type === 'cancelled') {
+            return Promise.resolve({
+              ok: false,
+              status: 'cancelled',
+              provider: 'google',
+              reason: input.response.reason,
+            });
+          }
+
+          if (input.response.type === 'error') {
+            return Promise.resolve({
+              ok: false,
+              status: 'error',
+              error: {
+                code: 'authorization_failed',
+                message: input.response.error.message,
+                stage: 'transport',
+                provider: 'google',
+                recoverable: true,
+              },
+            });
+          }
+
+          return Promise.resolve({
+            ok: true,
+            status: 'authenticated',
+            provider: 'google',
+            session,
+          });
+        },
       },
-      getSession() {
-        return Promise.resolve({ ok: true, data: null });
+    };
+
+    const started = await adapter.oauth?.startAuthorization({
+      provider: 'google',
+      redirectUri: 'ankh-app://auth/callback',
+      scopes: ['openid', 'email', 'profile'],
+      queryParams: { prompt: 'select_account' },
+    });
+
+    expect(adapter.oauth?.capabilities.providers).toEqual(['google', 'custom-sso']);
+    expect(started?.ok).toBe(true);
+    expect(started?.ok === true ? started.data.attemptId : undefined).toBe('oauth-attempt-1');
+    expect(started?.ok === true ? started.data.redirectUri : undefined).toBe(
+      'ankh-app://auth/callback',
+    );
+
+    const completed = await adapter.oauth?.completeAuthorization({
+      attemptId: 'oauth-attempt-1',
+      response: {
+        type: 'callback',
+        url: 'ankh-app://auth/callback?code=opaque-code&state=opaque-state',
       },
-      signInWithOAuth(input) {
-        return Promise.resolve({
-          ok: true,
-          data: {
-            provider: input.provider,
-            url: `https://auth.example.com/oauth/${input.provider}`,
-          },
-        });
+    });
+
+    expect(completed?.status).toBe('authenticated');
+    expect(completed?.ok === true ? completed.session : undefined).toEqual(session);
+  });
+
+  it('models user cancellation separately from OAuth failures', async () => {
+    const adapter: AuthAdapter = {
+      ...createBaseAdapter(),
+      oauth: {
+        capabilities: { providers: ['google'] },
+        startAuthorization(input) {
+          return Promise.resolve({
+            ok: true,
+            data: {
+              attemptId: 'oauth-attempt-2',
+              provider: input.provider,
+              authorizationUrl: 'https://auth.example.com/oauth/google',
+              redirectUri: input.redirectUri,
+            },
+          });
+        },
+        completeAuthorization(input) {
+          if (input.response.type === 'cancelled') {
+            return Promise.resolve({
+              ok: false,
+              status: 'cancelled',
+              provider: 'google',
+              reason: input.response.reason,
+            });
+          }
+
+          return Promise.resolve({
+            ok: false,
+            status: 'error',
+            error: {
+              code: 'invalid_callback',
+              message: 'The OAuth callback is invalid.',
+              stage: 'callback',
+              provider: 'google',
+              recoverable: true,
+            },
+          });
+        },
       },
     };
 
-    const result = await adapter.signInWithOAuth?.({
+    const cancelled = await adapter.oauth?.completeAuthorization({
+      attemptId: 'oauth-attempt-2',
+      response: { type: 'cancelled', reason: 'browser_dismissed' },
+    });
+
+    expect(AUTH_OAUTH_CANCELLATION_REASONS).toContain('provider_denied');
+    expect(AUTH_OAUTH_ERROR_CODES).toContain('pkce_mismatch');
+    expect(cancelled).toEqual({
+      ok: false,
+      status: 'cancelled',
       provider: 'google',
-      redirectTo: '/auth/callback',
-      scopes: ['openid', 'email', 'profile'],
+      reason: 'browser_dismissed',
     });
+  });
+
+  it('removes the superseded URL-only OAuth adapter surface', () => {
+    const source = readFileSync(
+      path.join(path.dirname(fileURLToPath(import.meta.url)), 'auth.ts'),
+      'utf8',
+    );
+    const removedSymbols = [
+      'SignInWith' + 'OAuthInput',
+      'AuthOAuth' + 'Redirect',
+      'CompleteOAuth' + 'SignInInput',
+      'signInWith' + 'OAuth',
+      'completeOAuth' + 'SignIn',
+      'supports' + 'OAuth',
+      'oauth' + 'Providers',
+    ];
 
-    expect(adapter.capabilities?.supportsOAuth).toBe(true);
-    expect(adapter.capabilities?.oauthProviders).toEqual(['google', 'custom-sso']);
-    expect(result?.ok).toBe(true);
-    expect(result?.ok === true ? result.data?.provider : undefined).toBe('google');
-    expect(result?.ok === true ? result.data?.url : undefined).toContain('/oauth/google');
+    for (const symbol of removedSymbols) {
+      expect(source).not.toContain(symbol);
+    }
   });
 });

package/src/auth.ts

@@ -1,3 +1,4 @@
+import type { SecretRef } from './secrets';
 import type { IconSpec } from './types';
 
 export const AUTH_IDENTIFIER_KINDS = ['email', 'phone', 'username'] as const;
@@ -79,9 +80,10 @@ export interface AuthOAuthProviderConfig {
   label?: string;
   enabled?: boolean;
   scopes?: string[];
-  redirectTo?: string;
   queryParams?: Record<string, string>;
   icon?: IconSpec;
+  /** Logical server-side secret reference; raw credentials must never be stored here. */
+  credentialsRef?: SecretRef;
 }
 
 export interface AuthOAuthConfig {
@@ -169,22 +171,139 @@ export interface VerifyOtpInput {
   metadata?: Record<string, unknown>;
 }
 
-export interface SignInWithOAuthInput {
+export const AUTH_OAUTH_ERROR_STAGES = [
+  'start',
+  'transport',
+  'callback',
+  'exchange',
+  'session',
+  'profile',
+] as const;
+export type AuthOAuthErrorStage = (typeof AUTH_OAUTH_ERROR_STAGES)[number];
+
+export const AUTH_OAUTH_ERROR_CODES = [
+  'oauth_unavailable',
+  'provider_disabled',
+  'provider_misconfigured',
+  'invalid_redirect_uri',
+  'authorization_failed',
+  'authorization_attempt_not_found',
+  'invalid_callback',
+  'state_mismatch',
+  'pkce_mismatch',
+  'callback_already_completed',
+  'code_exchange_failed',
+  'network_error',
+  'session_persistence_failed',
+  'profile_creation_failed',
+  'provider_error',
+] as const;
+export type AuthOAuthErrorCode = (typeof AUTH_OAUTH_ERROR_CODES)[number];
+
+export interface AuthOAuthError extends AuthAdapterError {
+  code: AuthOAuthErrorCode;
+  stage: AuthOAuthErrorStage;
+  provider?: AuthOAuthProviderId;
+  recoverable: boolean;
+}
+
+export const AUTH_OAUTH_TRANSPORT_CANCELLATION_REASONS = [
+  'user_cancelled',
+  'browser_dismissed',
+] as const;
+export type AuthOAuthTransportCancellationReason =
+  (typeof AUTH_OAUTH_TRANSPORT_CANCELLATION_REASONS)[number];
+
+export const AUTH_OAUTH_CANCELLATION_REASONS = [
+  ...AUTH_OAUTH_TRANSPORT_CANCELLATION_REASONS,
+  'provider_denied',
+] as const;
+export type AuthOAuthCancellationReason = (typeof AUTH_OAUTH_CANCELLATION_REASONS)[number];
+
+export const AUTH_OAUTH_TRANSPORT_ERROR_CODES = [
+  'browser_unavailable',
+  'transport_failed',
+] as const;
+export type AuthOAuthTransportErrorCode = (typeof AUTH_OAUTH_TRANSPORT_ERROR_CODES)[number];
+
+export interface AuthOAuthTransportError {
+  code: AuthOAuthTransportErrorCode;
+  message: string;
+  cause?: unknown;
+}
+
+export interface StartOAuthAuthorizationInput {
   provider: AuthOAuthProviderId;
-  redirectTo?: string;
-  scopes?: string[];
-  queryParams?: Record<string, string>;
-  metadata?: Record<string, unknown>;
+  redirectUri: string;
+  scopes?: readonly string[];
+  queryParams?: Readonly<Record<string, string>>;
 }
 
-export interface AuthOAuthRedirect {
+export interface AuthOAuthAuthorizationRequest {
+  attemptId: string;
   provider: AuthOAuthProviderId;
-  url: string;
+  authorizationUrl: string;
+  redirectUri: string;
 }
 
-export interface CompleteOAuthSignInInput {
-  url: string;
-  redirectTo?: string;
+export type AuthOAuthStartResult =
+  | {
+      ok: true;
+      data: AuthOAuthAuthorizationRequest;
+    }
+  | {
+      ok: false;
+      error: AuthOAuthError;
+    };
+
+export type AuthOAuthAuthorizationResponse =
+  | {
+      type: 'callback';
+      url: string;
+    }
+  | {
+      type: 'cancelled';
+      reason: AuthOAuthTransportCancellationReason;
+    }
+  | {
+      type: 'error';
+      error: AuthOAuthTransportError;
+    };
+
+export interface CompleteOAuthAuthorizationInput {
+  attemptId: string;
+  response: AuthOAuthAuthorizationResponse;
+}
+
+export type AuthOAuthCompletionResult =
+  | {
+      ok: true;
+      status: 'authenticated';
+      provider: AuthOAuthProviderId;
+      session: AuthSession;
+    }
+  | {
+      ok: false;
+      status: 'cancelled';
+      provider: AuthOAuthProviderId;
+      reason: AuthOAuthCancellationReason;
+    }
+  | {
+      ok: false;
+      status: 'error';
+      error: AuthOAuthError;
+    };
+
+export interface AuthOAuthCapabilities {
+  /** Enabled providers for which start and callback completion are operational. */
+  providers: readonly [AuthOAuthProviderId, ...AuthOAuthProviderId[]];
+}
+
+export interface AuthOAuthAdapter {
+  readonly capabilities: AuthOAuthCapabilities;
+
+  startAuthorization(input: StartOAuthAuthorizationInput): Promise<AuthOAuthStartResult>;
+  completeAuthorization(input: CompleteOAuthAuthorizationInput): Promise<AuthOAuthCompletionResult>;
 }
 
 export interface AuthAdapterCapabilities {
@@ -193,12 +312,15 @@ export interface AuthAdapterCapabilities {
   supportsPasswordReset: boolean;
   supportsOtp: boolean;
   supportsSessionRefresh: boolean;
-  supportsOAuth?: boolean;
-  oauthProviders?: AuthOAuthProviderId[];
 }
 
 export interface AuthAdapter {
   readonly capabilities?: AuthAdapterCapabilities;
+  /**
+   * Presence is the canonical OAuth capability signal. When present, both authorization start and
+   * callback completion are mandatory and operational for every advertised provider.
+   */
+  readonly oauth?: AuthOAuthAdapter;
 
   signIn(input: SignInInput): Promise<AuthResult<AuthSession>>;
   signUp(input: SignUpInput): Promise<AuthResult<AuthSession | AuthUser>>;
@@ -209,7 +331,4 @@ export interface AuthAdapter {
 
   requestPasswordReset?(input: PasswordResetInput): Promise<AuthResult>;
   verifyOtp?(input: VerifyOtpInput): Promise<AuthResult<AuthSession>>;
-
-  signInWithOAuth?(input: SignInWithOAuthInput): Promise<AuthResult<AuthOAuthRedirect>>;
-  completeOAuthSignIn?(input: CompleteOAuthSignInInput): Promise<AuthResult<AuthSession>>;
 }

package/src/index.ts

@@ -6,6 +6,8 @@ export * from './db';
 export * from './nutrition';
 export * from './requirements';
 export * from './runtimeCallbacks';
+export * from './secretManifest';
+export * from './secrets';
 export * from './state';
 export * from './storage';
 export * from './types';

package/src/secretManifest.ts

@@ -0,0 +1,12 @@
+import type { SecretStoreProvider } from './secrets';
+
+export interface InfraSecretStoreSpec {
+  provider: SecretStoreProvider;
+}
+
+declare module './types' {
+  interface InfraManifest {
+    /** Non-secret provider selection. Bootstrap credentials stay in trusted environment config. */
+    secretStore?: InfraSecretStoreSpec;
+  }
+}

package/src/secrets.test.ts

@@ -0,0 +1,88 @@
+import './secretManifest';
+
+import { describe, expect, test } from 'bun:test';
+
+import type { AuthOAuthProviderConfig } from './auth';
+import {
+  findForbiddenInlineSecretFields,
+  normalizeSecretRef,
+  normalizeSecretScope,
+  validateSecretPayload,
+} from './secrets';
+import type { InfraManifest } from './types';
+
+describe('secret-store contracts', () => {
+  test('normalizes logical secret references', () => {
+    expect(normalizeSecretRef('/auth//oauth/google/')).toEqual({
+      ok: true,
+      data: 'auth/oauth/google',
+    });
+  });
+
+  test('rejects invalid secret references', () => {
+    expect(normalizeSecretRef('Auth OAuth/Google')).toEqual({
+      ok: false,
+      error: {
+        code: 'invalid_reference',
+        message:
+          'Secret reference must contain lowercase path segments using letters, numbers, dots, underscores, or hyphens.',
+      },
+    });
+  });
+
+  test('normalizes project and environment scope', () => {
+    expect(normalizeSecretScope({ projectId: ' scanner ', environment: ' local ' })).toEqual({
+      ok: true,
+      data: { projectId: 'scanner', environment: 'local' },
+    });
+  });
+
+  test('validates non-empty string payloads without exposing values', () => {
+    expect(validateSecretPayload({ clientId: 'id', clientSecret: 'secret' })).toEqual({
+      ok: true,
+      data: { clientId: 'id', clientSecret: 'secret' },
+    });
+
+    const result = validateSecretPayload({ clientSecret: '' });
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe('invalid_payload');
+      expect(result.error.message).not.toContain('secret-value');
+    }
+  });
+
+  test('detects forbidden inline secret fields in manifest-shaped provider config', () => {
+    expect(
+      findForbiddenInlineSecretFields({
+        id: 'google',
+        credentialsRef: 'auth/oauth/google',
+        clientSecret: 'sentinel-secret-value',
+      }),
+    ).toEqual(['clientSecret']);
+  });
+
+  test('supports OAuth credential references and canonical infra provider selection', () => {
+    const provider: AuthOAuthProviderConfig = {
+      id: 'google',
+      enabled: true,
+      credentialsRef: 'auth/oauth/google',
+    };
+
+    const infra: InfraManifest = {
+      plugins: [],
+      secretStore: { provider: 'supabase-vault' },
+      auth: {
+        scope: 'global',
+        provider: 'supabase',
+        oauth: {
+          enabled: true,
+          callbackRoute: '/auth/callback',
+          providers: [provider],
+        },
+      },
+    };
+
+    expect(infra.secretStore?.provider).toBe('supabase-vault');
+    expect(infra.auth?.oauth?.providers[0]?.credentialsRef).toBe('auth/oauth/google');
+  });
+});