feat(auth): add core permission type schemas

- Add base OAuth scope constants
- Add Zod schemas for permission primitives
- Add NSID and MIME type validation patterns
- Export inferred TypeScript types

Author: bitbeckers

packages/sdk-core/src/auth/permissions.ts

@@ -0,0 +1,146 @@
+/**
+ * OAuth Scopes and Granular Permissions
+ *
+ * This module provides type-safe, Zod-validated OAuth scope and permission management
+ * for the ATProto SDK. It supports both legacy transitional scopes and the new
+ * granular permissions model.
+ *
+ * @see https://atproto.com/specs/oauth
+ * @see https://atproto.com/specs/permission
+ *
+ * @module auth/permissions
+ */
+
+import { z } from "zod";
+
+/**
+ * Base OAuth scope - required for all sessions
+ *
+ * @constant
+ */
+export const ATPROTO_SCOPE = 'atproto' as const;
+
+/**
+ * Transitional OAuth scopes for legacy compatibility.
+ *
+ * These scopes provide broad access and are maintained for backwards compatibility.
+ * New applications should use granular permissions instead.
+ *
+ * @deprecated Use granular permissions (account:*, repo:*, etc.) for better control
+ * @constant
+ */
+export const TRANSITION_SCOPES = {
+  /** Broad PDS permissions including record creation, blob uploads, and preferences */
+  GENERIC: 'transition:generic',
+  /** Direct messages access (requires transition:generic) */
+  CHAT: 'transition:chat.bsky',
+  /** Email address and confirmation status */
+  EMAIL: 'transition:email',
+} as const;
+
+/**
+ * Zod schema for transitional scopes.
+ *
+ * Validates that a scope string is one of the known transitional scopes.
+ *
+ * @example
+ * ```typescript
+ * TransitionScopeSchema.parse('transition:email'); // Valid
+ * TransitionScopeSchema.parse('invalid'); // Throws ZodError
+ * ```
+ */
+export const TransitionScopeSchema = z.enum([
+  'transition:generic',
+  'transition:chat.bsky',
+  'transition:email',
+]).describe('Legacy transitional OAuth scopes');
+
+/**
+ * Type for transitional scopes inferred from schema.
+ */
+export type TransitionScope = z.infer<typeof TransitionScopeSchema>;
+
+/**
+ * Zod schema for account permission attributes.
+ *
+ * Account attributes specify what aspect of the account is being accessed.
+ */
+export const AccountAttrSchema = z.enum(['email', 'repo']);
+
+/**
+ * Type for account attributes inferred from schema.
+ */
+export type AccountAttr = z.infer<typeof AccountAttrSchema>;
+
+/**
+ * Zod schema for account actions.
+ *
+ * Account actions specify the level of access (read-only or management).
+ */
+export const AccountActionSchema = z.enum(['read', 'manage']);
+
+/**
+ * Type for account actions inferred from schema.
+ */
+export type AccountAction = z.infer<typeof AccountActionSchema>;
+
+/**
+ * Zod schema for repository actions.
+ *
+ * Repository actions specify what operations can be performed on records.
+ */
+export const RepoActionSchema = z.enum(['create', 'update', 'delete']);
+
+/**
+ * Type for repository actions inferred from schema.
+ */
+export type RepoAction = z.infer<typeof RepoActionSchema>;
+
+/**
+ * Zod schema for identity permission attributes.
+ *
+ * Identity attributes specify what identity information can be managed.
+ */
+export const IdentityAttrSchema = z.enum(['handle', '*']);
+
+/**
+ * Type for identity attributes inferred from schema.
+ */
+export type IdentityAttr = z.infer<typeof IdentityAttrSchema>;
+
+/**
+ * Zod schema for MIME type patterns.
+ *
+ * Validates MIME type strings like "image/*" or "video/mp4".
+ *
+ * @example
+ * ```typescript
+ * MimeTypeSchema.parse('image/*'); // Valid
+ * MimeTypeSchema.parse('video/mp4'); // Valid
+ * MimeTypeSchema.parse('invalid'); // Throws ZodError
+ * ```
+ */
+export const MimeTypeSchema = z.string().regex(
+  /^[a-z]+\/[a-z0-9*+-]+$/i,
+  'Invalid MIME type pattern. Expected format: type/subtype (e.g., "image/*" or "video/mp4")'
+);
+
+/**
+ * Zod schema for NSID (Namespaced Identifier).
+ *
+ * NSIDs are reverse-DNS style identifiers used throughout ATProto
+ * (e.g., "app.bsky.feed.post" or "com.example.myrecord").
+ *
+ * @see https://atproto.com/specs/nsid
+ *
+ * @example
+ * ```typescript
+ * NsidSchema.parse('app.bsky.feed.post'); // Valid
+ * NsidSchema.parse('com.example.myrecord'); // Valid
+ * NsidSchema.parse('InvalidNSID'); // Throws ZodError
+ * ```
+ */
+export const NsidSchema = z.string().regex(
+  /^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+$/,
+  'Invalid NSID format. Expected reverse-DNS format (e.g., "app.bsky.feed.post")'
+);

packages/sdk-core/tests/auth/permissions.test.ts

@@ -0,0 +1,172 @@
+import { describe, it, expect } from "vitest";
+import {
+  ATPROTO_SCOPE,
+  TRANSITION_SCOPES,
+  TransitionScopeSchema,
+  AccountAttrSchema,
+  AccountActionSchema,
+  RepoActionSchema,
+  IdentityAttrSchema,
+  MimeTypeSchema,
+  NsidSchema,
+} from "../../src/auth/permissions.js";
+
+describe("Permission Constants", () => {
+  it("should export ATPROTO_SCOPE constant", () => {
+    expect(ATPROTO_SCOPE).toBe("atproto");
+  });
+
+  it("should export TRANSITION_SCOPES with correct values", () => {
+    expect(TRANSITION_SCOPES.GENERIC).toBe("transition:generic");
+    expect(TRANSITION_SCOPES.CHAT).toBe("transition:chat.bsky");
+    expect(TRANSITION_SCOPES.EMAIL).toBe("transition:email");
+  });
+});
+
+describe("TransitionScopeSchema", () => {
+  it("should accept valid transitional scopes", () => {
+    expect(TransitionScopeSchema.parse("transition:generic")).toBe("transition:generic");
+    expect(TransitionScopeSchema.parse("transition:chat.bsky")).toBe("transition:chat.bsky");
+    expect(TransitionScopeSchema.parse("transition:email")).toBe("transition:email");
+  });
+
+  it("should reject invalid transitional scopes", () => {
+    expect(() => TransitionScopeSchema.parse("atproto")).toThrow();
+    expect(() => TransitionScopeSchema.parse("transition:invalid")).toThrow();
+    expect(() => TransitionScopeSchema.parse("invalid")).toThrow();
+    expect(() => TransitionScopeSchema.parse("")).toThrow();
+  });
+});
+
+describe("AccountAttrSchema", () => {
+  it("should accept valid account attributes", () => {
+    expect(AccountAttrSchema.parse("email")).toBe("email");
+    expect(AccountAttrSchema.parse("repo")).toBe("repo");
+  });
+
+  it("should reject invalid account attributes", () => {
+    expect(() => AccountAttrSchema.parse("invalid")).toThrow();
+    expect(() => AccountAttrSchema.parse("handle")).toThrow();
+    expect(() => AccountAttrSchema.parse("")).toThrow();
+  });
+});
+
+describe("AccountActionSchema", () => {
+  it("should accept valid account actions", () => {
+    expect(AccountActionSchema.parse("read")).toBe("read");
+    expect(AccountActionSchema.parse("manage")).toBe("manage");
+  });
+
+  it("should reject invalid account actions", () => {
+    expect(() => AccountActionSchema.parse("create")).toThrow();
+    expect(() => AccountActionSchema.parse("delete")).toThrow();
+    expect(() => AccountActionSchema.parse("invalid")).toThrow();
+    expect(() => AccountActionSchema.parse("")).toThrow();
+  });
+});
+
+describe("RepoActionSchema", () => {
+  it("should accept valid repository actions", () => {
+    expect(RepoActionSchema.parse("create")).toBe("create");
+    expect(RepoActionSchema.parse("update")).toBe("update");
+    expect(RepoActionSchema.parse("delete")).toBe("delete");
+  });
+
+  it("should reject invalid repository actions", () => {
+    expect(() => RepoActionSchema.parse("read")).toThrow();
+    expect(() => RepoActionSchema.parse("manage")).toThrow();
+    expect(() => RepoActionSchema.parse("invalid")).toThrow();
+    expect(() => RepoActionSchema.parse("")).toThrow();
+  });
+});
+
+describe("IdentityAttrSchema", () => {
+  it("should accept valid identity attributes", () => {
+    expect(IdentityAttrSchema.parse("handle")).toBe("handle");
+    expect(IdentityAttrSchema.parse("*")).toBe("*");
+  });
+
+  it("should reject invalid identity attributes", () => {
+    expect(() => IdentityAttrSchema.parse("email")).toThrow();
+    expect(() => IdentityAttrSchema.parse("repo")).toThrow();
+    expect(() => IdentityAttrSchema.parse("invalid")).toThrow();
+    expect(() => IdentityAttrSchema.parse("")).toThrow();
+  });
+});
+
+describe("MimeTypeSchema", () => {
+  it("should accept valid MIME type patterns", () => {
+    expect(MimeTypeSchema.parse("image/*")).toBe("image/*");
+    expect(MimeTypeSchema.parse("video/*")).toBe("video/*");
+    expect(MimeTypeSchema.parse("audio/*")).toBe("audio/*");
+    expect(MimeTypeSchema.parse("text/html")).toBe("text/html");
+    expect(MimeTypeSchema.parse("application/json")).toBe("application/json");
+    expect(MimeTypeSchema.parse("image/png")).toBe("image/png");
+    expect(MimeTypeSchema.parse("video/mp4")).toBe("video/mp4");
+  });
+
+  it("should accept MIME types with numbers and hyphens", () => {
+    expect(MimeTypeSchema.parse("application/json-ld")).toBe("application/json-ld");
+    expect(MimeTypeSchema.parse("application/ld+json")).toBe("application/ld+json");
+    expect(MimeTypeSchema.parse("image/svg+xml")).toBe("image/svg+xml");
+  });
+
+  it("should reject invalid MIME type patterns", () => {
+    expect(() => MimeTypeSchema.parse("invalid")).toThrow();
+    expect(() => MimeTypeSchema.parse("image")).toThrow();
+    expect(() => MimeTypeSchema.parse("/png")).toThrow();
+    expect(() => MimeTypeSchema.parse("image/")).toThrow();
+    expect(() => MimeTypeSchema.parse("")).toThrow();
+  });
+
+  it("should accept MIME types in any case (case-insensitive)", () => {
+    // MIME types are case-insensitive per RFC 2045
+    expect(MimeTypeSchema.parse("IMAGE/*")).toBe("IMAGE/*");
+    expect(MimeTypeSchema.parse("Image/Png")).toBe("Image/Png");
+  });
+
+  it("should provide helpful error message for invalid MIME types", () => {
+    try {
+      MimeTypeSchema.parse("invalid");
+      expect.fail("Should have thrown");
+    } catch (error) {
+      const zodError = error as { issues: Array<{ message: string }> };
+      expect(zodError.issues[0].message).toContain("Invalid MIME type pattern");
+      expect(zodError.issues[0].message).toContain("type/subtype");
+    }
+  });
+});
+
+describe("NsidSchema", () => {
+  it("should accept valid NSID formats", () => {
+    expect(NsidSchema.parse("app.bsky.feed.post")).toBe("app.bsky.feed.post");
+    expect(NsidSchema.parse("com.example.myrecord")).toBe("com.example.myrecord");
+    expect(NsidSchema.parse("org.example.test.nested.record")).toBe("org.example.test.nested.record");
+  });
+
+  it("should accept NSIDs with hyphens", () => {
+    expect(NsidSchema.parse("com.example-app.record")).toBe("com.example-app.record");
+    expect(NsidSchema.parse("app.my-test.record")).toBe("app.my-test.record");
+  });
+
+  it("should reject invalid NSID formats", () => {
+    expect(() => NsidSchema.parse("InvalidNSID")).toThrow();
+    expect(() => NsidSchema.parse("example")).toThrow(); // Need at least one dot
+    expect(() => NsidSchema.parse(".example.com")).toThrow(); // Can't start with dot
+    expect(() => NsidSchema.parse("example.com.")).toThrow(); // Can't end with dot
+    expect(() => NsidSchema.parse("Example.com")).toThrow(); // Must be lowercase
+    expect(() => NsidSchema.parse("example..com")).toThrow(); // No consecutive dots
+    expect(() => NsidSchema.parse("")).toThrow();
+  });
+
+  it("should provide helpful error message for invalid NSIDs", () => {
+    try {
+      NsidSchema.parse("InvalidNSID");
+      expect.fail("Should have thrown");
+    } catch (error) {
+      const zodError = error as { issues: Array<{ message: string }> };
+      expect(zodError.issues[0].message).toContain("Invalid NSID format");
+      expect(zodError.issues[0].message).toContain("reverse-DNS");
+    }
+  });
+});