@ankhorage/permissions 0.1.0

package/src/web/index.test.ts

@@ -0,0 +1,205 @@
+import { describe, expect, test } from 'bun:test';
+
+import { Permission } from '../registry/permissions';
+import { createWebPermissionClient, type WebPermissionClientOptions } from './index';
+
+describe('createWebPermissionClient', () => {
+  test('returns unavailable for unsupported web permissions', async () => {
+    const client = createWebPermissionClient({ global: {} });
+
+    const state = await client.getStatus(Permission.MediaLibrary);
+
+    expect(state).toMatchObject({
+      status: 'unavailable',
+      canAskAgain: false,
+    });
+  });
+
+  test('reads notification permission structurally', async () => {
+    const client = createWebPermissionClient({
+      global: {
+        Notification: {
+          permission: 'granted',
+          requestPermission: () => 'granted',
+        },
+      },
+    });
+
+    const state = await client.getStatus(Permission.Notifications);
+
+    expect(state).toMatchObject({
+      status: 'granted',
+      granted: true,
+    });
+  });
+
+  test('requests notifications without throwing on denial', async () => {
+    const client = createWebPermissionClient({
+      global: {
+        Notification: {
+          permission: 'default',
+          requestPermission: () => Promise.resolve('denied'),
+        },
+      },
+    });
+
+    const state = await client.request(Permission.Notifications);
+
+    expect(state).toMatchObject({
+      status: 'denied',
+      granted: false,
+    });
+  });
+
+  test('returns unavailable when notification request throws', async () => {
+    const client = createWebPermissionClient({
+      global: {
+        Notification: {
+          permission: 'default',
+          requestPermission: () => {
+            throw Object.assign(new Error('blocked'), { name: 'SecurityError' });
+          },
+        },
+      },
+    });
+
+    const state = await client.request(Permission.Notifications);
+
+    expect(state).toMatchObject({
+      status: 'unavailable',
+      granted: false,
+      reason: 'Notification permission request failed: SecurityError.',
+    });
+  });
+
+  test('uses Permissions API for location status when available', async () => {
+    const client = createWebPermissionClient({
+      global: {
+        navigator: {
+          permissions: {
+            query: () => Promise.resolve({ state: 'prompt' }),
+          },
+        },
+      },
+    });
+
+    const state = await client.getStatus(Permission.LocationForeground);
+
+    expect(state).toMatchObject({
+      status: 'unknown',
+      canAskAgain: true,
+    });
+  });
+
+  test('returns blocked for media in insecure contexts', async () => {
+    const client = createWebPermissionClient({
+      global: {
+        isSecureContext: false,
+      },
+    });
+
+    const state = await client.getStatus(Permission.Camera);
+
+    expect(state).toMatchObject({
+      status: 'blocked',
+      canAskAgain: false,
+    });
+  });
+
+  test('requests geolocation without a 1ms timeout', async () => {
+    let requestedOptions:
+      | {
+          readonly maximumAge?: number;
+          readonly timeout?: number;
+        }
+      | undefined;
+    const client = createWebPermissionClient({
+      global: {
+        navigator: {
+          geolocation: {
+            getCurrentPosition: (success, _error, options) => {
+              requestedOptions = options;
+              success();
+            },
+          },
+        },
+      },
+    });
+
+    const state = await client.request(Permission.LocationForeground);
+
+    expect(state.status).toBe('granted');
+    expect(requestedOptions).toEqual({ maximumAge: 0 });
+  });
+
+  test('requests media with getUserMedia and stops tracks', async () => {
+    let stopped = false;
+    const global: WebPermissionClientOptions['global'] = {
+      navigator: {
+        mediaDevices: {
+          getUserMedia: () =>
+            Promise.resolve({
+              getTracks: () => [
+                {
+                  stop: () => {
+                    stopped = true;
+                  },
+                },
+              ],
+            }),
+        },
+      },
+    };
+    const client = createWebPermissionClient({ global });
+
+    const state = await client.request(Permission.Microphone);
+
+    expect(state).toMatchObject({
+      status: 'granted',
+      granted: true,
+    });
+    expect(stopped).toBe(true);
+  });
+
+  test('maps missing media devices to unavailable', async () => {
+    const client = createWebPermissionClient({
+      global: {
+        navigator: {
+          mediaDevices: {
+            getUserMedia: () =>
+              Promise.reject(Object.assign(new Error('missing'), { name: 'NotFoundError' })),
+          },
+        },
+      },
+    });
+
+    const state = await client.request(Permission.Camera);
+
+    expect(state).toMatchObject({
+      status: 'unavailable',
+      granted: false,
+      reason: 'Media permission request failed: NotFoundError.',
+    });
+  });
+
+  test('maps user media denial to denied', async () => {
+    const client = createWebPermissionClient({
+      global: {
+        navigator: {
+          mediaDevices: {
+            getUserMedia: () =>
+              Promise.reject(Object.assign(new Error('denied'), { name: 'NotAllowedError' })),
+          },
+        },
+      },
+    });
+
+    const state = await client.request(Permission.Camera);
+
+    expect(state).toMatchObject({
+      status: 'denied',
+      granted: false,
+      reason: 'Media permission request was denied: NotAllowedError.',
+    });
+  });
+});

package/src/web/index.ts

@@ -0,0 +1,390 @@
+import type { PermissionClient } from '../client/types';
+import { assertKnownPermission, Permission } from '../registry/permissions';
+import {
+  createPermissionState,
+  type PermissionState,
+  type PermissionStatus,
+} from '../state/permissionState';
+
+type BrowserPermissionName = 'camera' | 'microphone' | 'geolocation' | 'notifications';
+type BrowserPermissionState = 'granted' | 'denied' | 'prompt';
+type NotificationPermissionState = 'default' | 'denied' | 'granted';
+
+interface BrowserPermissionStatus {
+  readonly state: BrowserPermissionState;
+}
+
+interface BrowserPermissions {
+  query(descriptor: { readonly name: BrowserPermissionName }): Promise<BrowserPermissionStatus>;
+}
+
+interface MediaStreamTrackLike {
+  stop(): void;
+}
+
+interface MediaStreamLike {
+  getTracks(): readonly MediaStreamTrackLike[];
+}
+
+interface MediaDevicesLike {
+  getUserMedia(constraints: {
+    readonly audio?: boolean;
+    readonly video?: boolean;
+  }): Promise<MediaStreamLike>;
+}
+
+interface GeolocationLike {
+  getCurrentPosition(
+    success: () => void,
+    error: () => void,
+    options?: {
+      readonly maximumAge?: number;
+      readonly timeout?: number;
+    },
+  ): void;
+}
+
+interface NavigatorLike {
+  readonly permissions?: BrowserPermissions;
+  readonly mediaDevices?: MediaDevicesLike;
+  readonly geolocation?: GeolocationLike;
+}
+
+interface NotificationLike {
+  readonly permission: NotificationPermissionState;
+  requestPermission(): Promise<NotificationPermissionState> | NotificationPermissionState;
+}
+
+interface WebGlobalLike {
+  readonly isSecureContext?: boolean;
+  readonly navigator?: NavigatorLike;
+  readonly Notification?: NotificationLike;
+}
+
+/***
+ * Options for the browser permission adapter.
+ */
+export interface WebPermissionClientOptions {
+  readonly global?: WebGlobalLike;
+}
+
+/***
+ * Creates a browser permission client using guarded structural globals.
+ *
+ * @readme
+ * Unsupported web APIs resolve to `status: 'unavailable'`. The adapter does not
+ * import DOM types and does not assume it is running in a browser.
+ */
+export function createWebPermissionClient(
+  options: WebPermissionClientOptions = {},
+): PermissionClient {
+  const global = options.global ?? getDefaultGlobal();
+
+  return {
+    async getStatus(permission) {
+      const knownPermission = assertKnownPermission(permission);
+
+      switch (knownPermission) {
+        case Permission.Notifications:
+          return getNotificationStatus(knownPermission, global);
+        case Permission.LocationForeground:
+          return getPermissionApiStatus(
+            knownPermission,
+            global,
+            'geolocation',
+            'Geolocation is unavailable in this environment.',
+          );
+        case Permission.Camera:
+          return getMediaStatus(knownPermission, global, 'camera');
+        case Permission.Microphone:
+          return getMediaStatus(knownPermission, global, 'microphone');
+        default:
+          return unavailable(
+            knownPermission,
+            'This permission is not supported by the web adapter.',
+          );
+      }
+    },
+
+    async request(permission) {
+      const knownPermission = assertKnownPermission(permission);
+
+      switch (knownPermission) {
+        case Permission.Notifications:
+          return requestNotifications(knownPermission, global);
+        case Permission.LocationForeground:
+          return requestGeolocation(knownPermission, global);
+        case Permission.Camera:
+          return requestMedia(knownPermission, global, { video: true });
+        case Permission.Microphone:
+          return requestMedia(knownPermission, global, { audio: true });
+        default:
+          return unavailable(
+            knownPermission,
+            'This permission is not supported by the web adapter.',
+          );
+      }
+    },
+  };
+}
+
+function getDefaultGlobal(): WebGlobalLike {
+  return globalThis as WebGlobalLike;
+}
+
+function getNotificationStatus(permission: Permission, global: WebGlobalLike): PermissionState {
+  if (global.Notification === undefined) {
+    return unavailable(permission, 'Notification API is unavailable.');
+  }
+
+  return stateFromNotificationPermission(permission, global.Notification.permission);
+}
+
+async function requestNotifications(
+  permission: Permission,
+  global: WebGlobalLike,
+): Promise<PermissionState> {
+  if (global.Notification === undefined) {
+    return unavailable(permission, 'Notification API is unavailable.');
+  }
+
+  try {
+    const result = await global.Notification.requestPermission();
+
+    return stateFromNotificationPermission(permission, result);
+  } catch (error) {
+    return unavailable(
+      permission,
+      `Notification permission request failed${formatErrorName(error)}.`,
+    );
+  }
+}
+
+async function getPermissionApiStatus(
+  permission: Permission,
+  global: WebGlobalLike,
+  name: BrowserPermissionName,
+  unavailableReason: string,
+): Promise<PermissionState> {
+  if (global.navigator?.permissions === undefined) {
+    return unavailable(permission, unavailableReason);
+  }
+
+  try {
+    const status = await global.navigator.permissions.query({ name });
+
+    return stateFromBrowserPermission(permission, status.state);
+  } catch {
+    return unavailable(permission, unavailableReason);
+  }
+}
+
+async function getMediaStatus(
+  permission: Permission,
+  global: WebGlobalLike,
+  name: BrowserPermissionName,
+): Promise<PermissionState> {
+  if (global.navigator?.permissions !== undefined) {
+    try {
+      const status = await global.navigator.permissions.query({ name });
+
+      return stateFromBrowserPermission(permission, status.state);
+    } catch {
+      return getMediaAvailability(permission, global);
+    }
+  }
+
+  return getMediaAvailability(permission, global);
+}
+
+function getMediaAvailability(permission: Permission, global: WebGlobalLike): PermissionState {
+  if (global.isSecureContext === false) {
+    return createPermissionState({
+      permission,
+      status: 'blocked',
+      canAskAgain: false,
+      reason: 'Media permissions require a secure context.',
+    });
+  }
+
+  if (global.navigator?.mediaDevices?.getUserMedia === undefined) {
+    return unavailable(permission, 'Media devices API is unavailable.');
+  }
+
+  return createPermissionState({
+    permission,
+    status: 'unknown',
+    canAskAgain: true,
+  });
+}
+
+async function requestGeolocation(
+  permission: Permission,
+  global: WebGlobalLike,
+): Promise<PermissionState> {
+  if (global.isSecureContext === false) {
+    return createPermissionState({
+      permission,
+      status: 'blocked',
+      canAskAgain: false,
+      reason: 'Geolocation requires a secure context.',
+    });
+  }
+
+  if (global.navigator?.geolocation === undefined) {
+    return unavailable(permission, 'Geolocation API is unavailable.');
+  }
+
+  return new Promise((resolve) => {
+    global.navigator?.geolocation?.getCurrentPosition(
+      () => {
+        resolve(
+          createPermissionState({
+            permission,
+            status: 'granted',
+            canAskAgain: true,
+            requestedAt: new Date(),
+          }),
+        );
+      },
+      () => {
+        resolve(
+          createPermissionState({
+            permission,
+            status: 'denied',
+            canAskAgain: false,
+            requestedAt: new Date(),
+          }),
+        );
+      },
+      { maximumAge: 0 },
+    );
+  });
+}
+
+async function requestMedia(
+  permission: Permission,
+  global: WebGlobalLike,
+  constraints: {
+    readonly audio?: boolean;
+    readonly video?: boolean;
+  },
+): Promise<PermissionState> {
+  const availability = getMediaAvailability(permission, global);
+
+  if (availability.status !== 'unknown') {
+    return availability;
+  }
+
+  try {
+    const stream = await global.navigator?.mediaDevices?.getUserMedia(constraints);
+
+    for (const track of stream?.getTracks() ?? []) {
+      track.stop();
+    }
+
+    return createPermissionState({
+      permission,
+      status: 'granted',
+      canAskAgain: true,
+      requestedAt: new Date(),
+    });
+  } catch (error) {
+    return stateFromMediaError(permission, error);
+  }
+}
+
+function stateFromMediaError(permission: Permission, error: unknown): PermissionState {
+  const errorName = getErrorName(error);
+  const unavailableErrorNames = new Set([
+    'AbortError',
+    'NotFoundError',
+    'NotReadableError',
+    'OverconstrainedError',
+    'SecurityError',
+  ]);
+
+  if (errorName !== undefined && unavailableErrorNames.has(errorName)) {
+    return createPermissionState({
+      permission,
+      status: 'unavailable',
+      canAskAgain: false,
+      requestedAt: new Date(),
+      reason: `Media permission request failed: ${errorName}.`,
+    });
+  }
+
+  return createPermissionState({
+    permission,
+    status: 'denied',
+    canAskAgain: false,
+    requestedAt: new Date(),
+    reason:
+      errorName === undefined
+        ? 'Media permission request was denied.'
+        : `Media permission request was denied: ${errorName}.`,
+  });
+}
+
+function stateFromNotificationPermission(
+  permission: Permission,
+  status: NotificationPermissionState,
+): PermissionState {
+  if (status === 'granted') {
+    return createPermissionState({
+      permission,
+      status: 'granted',
+      canAskAgain: true,
+    });
+  }
+
+  if (status === 'denied') {
+    return createPermissionState({
+      permission,
+      status: 'denied',
+      canAskAgain: false,
+    });
+  }
+
+  return createPermissionState({
+    permission,
+    status: 'unknown',
+    canAskAgain: true,
+  });
+}
+
+function stateFromBrowserPermission(
+  permission: Permission,
+  status: BrowserPermissionState,
+): PermissionState {
+  const normalizedStatus: PermissionStatus = status === 'prompt' ? 'unknown' : status;
+
+  return createPermissionState({
+    permission,
+    status: normalizedStatus,
+    canAskAgain: status === 'prompt' || status === 'granted',
+  });
+}
+
+function unavailable(permission: Permission, reason: string): PermissionState {
+  return createPermissionState({
+    permission,
+    status: 'unavailable',
+    canAskAgain: false,
+    reason,
+  });
+}
+
+function formatErrorName(error: unknown): string {
+  const errorName = getErrorName(error);
+
+  return errorName === undefined ? '' : `: ${errorName}`;
+}
+
+function getErrorName(error: unknown): string | undefined {
+  if (typeof error !== 'object' || error === null || !('name' in error)) {
+    return undefined;
+  }
+
+  return typeof error.name === 'string' && error.name.length > 0 ? error.name : undefined;
+}