Migrate from Clerk

import { betterIam } from 'better-iam';
import { postgresAdapter } from 'better-iam/adapter-postgres';
import { sendEmail } from './mail';

export const iam = betterIam({
  database: postgresAdapter({ connectionString: process.env.DATABASE_URL! }),
  secret: process.env.BETTER_IAM_SECRET!,
  baseURL: process.env.BETTER_IAM_BASE_URL!,
  authentication: {
    sendEmail,
    passwordlessEmail: true,
  },
  onboarding: { mode: 'linked' }, // people in several organizations can switch between their accounts
  permissions: {
    identityAttributes: { clerkId: 'string', plan: 'string' },
    resourceTypes: {
      invoice: { actions: ['invoices:read', 'invoices:create'] },
    },
  },
});

npx better-iam migrate --config better-iam.config.mjs
npx better-iam store-export --config better-iam.config.mjs --output before-clerk-import.jsonl

import { createReadStream } from 'node:fs';
import { readFile, writeFile } from 'node:fs/promises';
import { createInterface } from 'node:readline';
import { iam } from '../iam';

type ClerkOrganization = { id: string; name: string; ownerUserId: string };
type ClerkUser = {
  id: string;
  first_name: string | null;
  last_name: string | null;
  primary_email_address_id: string | null;
  email_addresses: Array<{ id: string; email_address: string; verification?: { status: string } | null }>;
};

const credential = { token: process.env.BETTER_IAM_TOKEN! };
const rootTenantId = process.env.ROOT_TENANT_ID!;

const owners = new Map<string, { email: string; verified: boolean; name: string }>();
for await (const line of createInterface({ input: createReadStream('clerk/users.ndjson'), crlfDelay: Infinity })) {
  if (!line.trim()) continue;
  const user = JSON.parse(line) as ClerkUser;
  const primary = user.email_addresses.find((address) => address.id === user.primary_email_address_id);
  if (!primary) continue;
  const name = [user.first_name, user.last_name].filter(Boolean).join(' ') || primary.email_address;
  owners.set(user.id, { email: primary.email_address, verified: primary.verification?.status === 'verified', name });
}

const organizations = JSON.parse(await readFile('clerk/organizations.json', 'utf8')) as ClerkOrganization[];
organizations.push({ id: 'personal', name: 'Personal accounts', ownerUserId: process.env.PERSONAL_OWNER_USER_ID! });

const tenantMap: Record<string, string> = {};
for (const organization of organizations) {
  const owner = owners.get(organization.ownerUserId);
  if (!owner) throw new Error(`No email for the owner of ${organization.name}`);
  const { tenant } = await iam.api.tenants.create(credential, {
    parentId: rootTenantId,
    type: 'organization',
    name: organization.name,
    ownerEmail: owner.email,
    activate: true, // active now; the owner's account is created without an invitation
    ownerName: owner.name,
    ownerEmailVerified: owner.verified,
  });
  tenantMap[organization.id] = tenant.id;
}
await writeFile('clerk/tenant-map.json', JSON.stringify(tenantMap, null, 2));

npx tsx scripts/clerk-create-tenants.ts

import { readFile } from 'node:fs/promises';
import { iam } from '../iam';

type ClerkRole = { key: string; name: string; permissions: string[] };

// Clerk permission key -> Better IAM action.
const actionFor: Record<string, string> = {
  'org:invoices:read': 'invoices:read',
  'org:invoices:create': 'invoices:create',
};

const credential = { token: process.env.BETTER_IAM_TOKEN! };

export async function applyClerkRoles(tenantId: string): Promise<Map<string, string>> {
  const roles = JSON.parse(await readFile('clerk/roles.json', 'utf8')) as ClerkRole[];
  await iam.api.config.apply(credential, {
    tenantId,
    config: {
      version: 1,
      roles: roles.map((role) => {
        // Clerk's system permissions (org:sys_*) correspond to Better IAM's own iam:* actions (see below).
        const permissions = role.permissions
          .filter((key) => !key.startsWith('org:sys_'))
          .map((key) => {
            const action = actionFor[key];
            if (!action) throw new Error(`No action mapped for Clerk permission ${key}`);
            return action;
          });
        // A permissions list must name at least one action; a role without any grants nothing yet.
        return permissions.length ? { name: role.name, permissions } : { name: role.name };
      }),
    },
  });
  const byName = new Map((await iam.api.roles.list(credential, { tenantId })).map((role) => [role.name, role.id]));
  // Clerk role key -> Better IAM role ID.
  return new Map(roles.flatMap((role) => (byName.has(role.name) ? [[role.key, byName.get(role.name)!]] : [])));
}

import { createReadStream } from 'node:fs';
import { readFile, writeFile } from 'node:fs/promises';
import { createInterface } from 'node:readline';
import { iam } from '../iam';
import { applyClerkRoles } from './clerk-roles';

type ClerkUser = {
  id: string;
  first_name: string | null;
  last_name: string | null;
  primary_email_address_id: string | null;
  email_addresses: Array<{ id: string; email_address: string; verification?: { status: string } | null }>;
  external_accounts?: Array<{ provider: string; provider_user_id: string }>;
  public_metadata: Record<string, unknown>;
  banned: boolean;
};
type Membership = { userId: string; role: string };
type Link = { providerId: string; issuer: string };

// Email domains of customers who sign in through their own SSO: never imported.
const ENTERPRISE_DOMAINS = new Set(['acme.com']);

// Clerk external account provider -> the OAuth connection that replaces it, per Clerk organization ('personal' for
// people without one). providerId is the connection's id in sso.ts; issuer is the provider's `iss`, exactly.
const OAUTH_CONNECTIONS: Record<string, Record<string, Link>> = {
  personal: {
    oauth_google: { providerId: 'personal-google', issuer: 'https://accounts.google.com' },
  },
};

const credential = { token: process.env.BETTER_IAM_TOKEN! };

const users = new Map<string, ClerkUser>();
for await (const line of createInterface({ input: createReadStream('clerk/users.ndjson'), crlfDelay: Infinity })) {
  if (line.trim()) {
    const user = JSON.parse(line) as ClerkUser;
    users.set(user.id, user);
  }
}

function primaryAddress(user: ClerkUser) {
  return user.email_addresses.find((address) => address.id === user.primary_email_address_id);
}

/** One link per Better IAM connection, from the user's Clerk external accounts. */
function providerLinks(user: ClerkUser, clerkOrgId: string) {
  const targets = OAUTH_CONNECTIONS[clerkOrgId] ?? {};
  const links = new Map<string, Link & { subject: string }>();
  for (const account of user.external_accounts ?? []) {
    const target = targets[account.provider];
    if (target) links.set(target.providerId, { ...target, subject: account.provider_user_id });
  }
  return [...links.values()];
}

async function existingEmails(tenantId: string): Promise<Set<string>> {
  const emails = new Set<string>();
  for (let offset = 0; ; offset += 1000) {
    const page = await iam.api.identities.list(credential, { tenantId, kind: 'user', limit: 1000, offset });
    for (const identity of page) if (identity.email) emails.add(identity.email);
    if (page.length < 1000) return emails;
  }
}

async function importTenant(clerkOrgId: string, tenantId: string, memberships: Membership[]): Promise<void> {
  const roleIds = await applyClerkRoles(tenantId);
  const seen = await existingEmails(tenantId);

  const rows = memberships.flatMap(({ userId, role }) => {
    const user = users.get(userId);
    const address = user && primaryAddress(user);
    const email = address?.email_address.trim().toLowerCase();
    if (!user || !address || !email || user.banned) return []; // no email, or banned: not imported
    if (ENTERPRISE_DOMAINS.has(email.split('@')[1]!)) return []; // arrives through SSO
    if (seen.has(email)) return []; // already imported, or the owner
    seen.add(email);
    const name = [user.first_name, user.last_name].filter(Boolean).join(' ') || email;
    const plan = user.public_metadata.plan;
    return [{
      user,
      entry: {
        email,
        name,
        emailVerified: address.verification?.status === 'verified',
        providers: providerLinks(user, clerkOrgId),
        attributes: { clerkId: user.id, ...(typeof plan === 'string' ? { plan } : {}) },
        roleIds: roleIds.has(role) ? [roleIds.get(role)!] : [],
      },
    }];
  });

  const idMap: Record<string, string> = {};
  for (let start = 0; start < rows.length; start += 100) {
    const batch = rows.slice(start, start + 100);
    const { identities } = await iam.api.identities.createMany(credential, {
      tenantId,
      identities: batch.map((row) => row.entry),
    });
    batch.forEach((row, i) => (idMap[row.user.id] = identities[i]!.id));
  }
  await writeFile(`clerk/id-map-${clerkOrgId}.json`, JSON.stringify(idMap, null, 2));
  console.log(`${clerkOrgId}: imported ${rows.length}`);
}

const tenantMap = JSON.parse(await readFile('clerk/tenant-map.json', 'utf8')) as Record<string, string>;
const inAnOrganization = new Set<string>();
for (const [clerkOrgId, tenantId] of Object.entries(tenantMap)) {
  if (clerkOrgId === 'personal') continue;
  const memberships = JSON.parse(await readFile(`clerk/memberships-${clerkOrgId}.json`, 'utf8')) as Membership[];
  memberships.forEach((membership) => inAnOrganization.add(membership.userId));
  await importTenant(clerkOrgId, tenantId, memberships);
}

// Everyone without an organization goes into the personal tenant, with no role.
const personal = [...users.keys()].filter((id) => !inAnOrganization.has(id)).map((userId) => ({ userId, role: '' }));
await importTenant('personal', tenantMap.personal!, personal);

npx tsx scripts/clerk-import-members.ts

import { createOAuthLogin } from 'better-iam/oauth';
import { iam } from './iam';

export const login = createOAuthLogin({
  ...iam.protocolHost,
  trustedOrigins: ['https://app.example.com'],
  connections: [
    {
      id: 'personal-google',
      tenantId: process.env.PERSONAL_TENANT_ID!,
      kind: 'google',
      clientId: process.env.GOOGLE_CLIENT_ID!,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
      redirectUri: 'https://app.example.com/oauth/personal-google/callback',
    },
    {
      id: 'acme-entra',
      tenantId: process.env.ACME_TENANT_ID!,
      kind: 'microsoft',
      microsoftTenant: process.env.ACME_ENTRA_TENANT_ID!,
      clientId: process.env.ACME_ENTRA_CLIENT_ID!,
      clientSecret: process.env.ACME_ENTRA_CLIENT_SECRET!,
      redirectUri: 'https://app.example.com/oauth/acme-entra/callback',
    },
  ],
});
iam.useProtocol(login);

import { NextResponse } from 'next/server';
import { createIamMiddleware } from '@better-iam/next/edge';

export const middleware = createIamMiddleware({
  loginPath: '/login',
  publicPaths: ['/', '/pricing', '/login'],
  next: (init) => NextResponse.next(init),
});
export const config = { matcher: ['/((?!_next|favicon.ico).*)'] };

import { iamNext } from '@/lib/iam-next';

export default async function Dashboard() {
  const current = await iamNext.getSession();
  if (!current) return <a href="/login">Sign in</a>;
  return <h1>Welcome, {current.identity.name}</h1>;
}