// The authorization pages as this checkout draws them, in any state, as // pictures to open (.claude/skills/ui). Starts `pds serve` on a data // directory of its own, with a PLC directory of its own and two accounts, // makes a PAR for the state named, drives Chromium to it, and writes // target/look/--.png. `just look` builds first. // // node look.mjs [--scope ''] [--hint] [--details] [--phone | --desktop] [--light | --dark] // node look.mjs email [--phone | --desktop] [--light | --dark] // // A `--scope` with `include:` or `space:` tokens has them resolved from the // harness's permission sets and space type declarations (lib/sets.mjs), // hosted on a PDS of their own. // // States: sign-in, wrong-password, rate-limited, email-code, choose, // consent, ended, busy, error, add-passkey, passkey-added, no-passkey. // Without --phone or --desktop it draws both, // desktop in light and the phone in dark; --light or --dark draws both // sizes in that scheme. Answers that the server's API gives the page are // the server's own, but for rate-limited, email-code, ended and busy, whose // answers this gives the page itself, as the server would give them. The // passkey states run the server on `http://localhost:`, an RP ID a // browser takes, with Chromium's virtual authenticator (spec/PASSKEYS.md). // // `email ` draws the HTML part of an email of that kind // (spec/EMAIL.md, "The message"), as the server sent it to an SMTP server // this starts, after asking for it as alice would, to // target/look/email---.png; `email all` draws every // kind, each with a server of its own. // // It says when a view is wider than the screen, naming the element that // runs past the edge. import { spawn } from 'node:child_process' import { createHash, randomBytes, webcrypto } from 'node:crypto' import { mkdirSync, mkdtempSync, openSync } from 'node:fs' import { createServer } from 'node:net' import { tmpdir } from 'node:os' import { join, resolve } from 'node:path' import { TestPlc } from '@atproto/dev-env' import { Secp256k1Keypair } from '@atproto/crypto' import { chromium } from 'playwright' import { hostSets } from './lib/sets.mjs' import { partsOf, startSmtp } from './lib/smtp.mjs' const STATES = ['sign-in', 'wrong-password', 'rate-limited', 'email-code', 'choose', 'consent', 'ended', 'busy', 'error', 'add-passkey', 'passkey-added', 'no-passkey', 'email'] const PASSKEY_STATES = ['add-passkey', 'passkey-added', 'no-passkey'] const KINDS = ['confirmEmail', 'updateEmail', 'resetPassword', 'signInAuthFactor', 'deleteAccount', 'plcOperation'] const args = process.argv.slice(2) const state = args[0] const kind = state === 'email' ? args[1] : undefined const flag = (f) => args.includes(f) const value = (f) => (args.includes(f) ? args[args.indexOf(f) + 1] : undefined) if (!STATES.includes(state) || (state === 'email' && ![...KINDS, 'all'].includes(kind))) { console.error(`usage: node look.mjs <${STATES.filter((s) => s !== 'email').join('|')}> [--scope ''] [--hint] [--details] [--phone | --desktop] [--light | --dark]`) console.error(` node look.mjs email <${KINDS.join('|')}|all> [--phone | --desktop] [--light | --dark]`) process.exit(2) } if (kind === 'all') { let failed = 0 for (const k of KINDS) { const code = await new Promise((ok) => spawn(process.execPath, [process.argv[1], 'email', k, ...args.slice(2)], { stdio: 'inherit' }).on('exit', ok)) if (code) failed = code } process.exit(failed) } const root = resolve(new URL('..', import.meta.url).pathname) const out = join(root, 'target/look') mkdirSync(out, { recursive: true }) const freePort = () => new Promise((ok) => { const s = createServer() s.listen(0, '127.0.0.1', () => { const { port } = s.address() s.close(() => ok(port)) }) }) // ------------------------------------------------------------ the server const plc = await TestPlc.create({}) const port = await freePort() const url = `http://${PASSKEY_STATES.includes(state) ? 'localhost' : '127.0.0.1'}:${port}` const rotation = await Secp256k1Keypair.create({ exportable: true }) const dataDir = mkdtempSync(join(tmpdir(), 'pds-look-')) const smtp = state === 'email' ? await startSmtp({ user: 'look', password: 'look-pass', from: 'pds@localhost' }) : undefined const log = join(dataDir, '..', `pds-look-${port}.log`) const sets = /(^| )(include|space)[:?]/.test(value('--scope') ?? '') ? await hostSets(plc.url) : undefined const server = spawn(join(root, 'target/release/pds'), ['serve'], { env: { ...process.env, PDS_PORT: String(port), PDS_DATA_DIR: dataDir, PDS_HOSTNAME: 'localhost', PDS_PUBLIC_URL: url, PDS_HANDLE_DOMAINS: '.test', PDS_PLC_URL: plc.url, PDS_PLC_ROTATION_KEY_HEX: Buffer.from(await rotation.export()).toString('hex'), PDS_ADMIN_PASSWORD: 'admin-pass', PDS_INVITE_REQUIRED: 'false', PDS_RATE_LIMITS_ENABLED: 'false', PDS_DEV_MAIL_DIR: mkdtempSync(join(tmpdir(), 'pds-look-mail-')), ...(smtp ? { PDS_EMAIL_SMTP_URL: smtp.url, PDS_EMAIL_FROM: smtp.from } : {}), ...(sets ? { PDS_LEXICON_AUTHORITY_DID: sets.did, PDS_DISABLE_SSRF_PROTECTION: 'true' } : {}), }, stdio: ['ignore', openSync(log, 'a'), openSync(log, 'a')], }) const stop = async (code) => { server.kill() smtp?.close() await sets?.pds.close() await plc.close() process.exit(code) } for (let t = 0; ; t++) { try { if ((await fetch(`${url}/xrpc/com.atproto.server.describeServer`)).ok) break } catch {} if (t > 300) { console.error(`pds did not start; its log is ${log}`) await stop(1) } await new Promise((ok) => setTimeout(ok, 50)) } const ACCOUNTS = [ { handle: 'alice.test', email: 'alice@example.com', password: 'alice-pass' }, { handle: 'rather-long-handle.test', email: 'long@example.com', password: 'long-pass' }, ] for (const a of ACCOUNTS) { const r = await fetch(`${url}/xrpc/com.atproto.server.createAccount`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(a) }) if (!r.ok) { console.error(`createAccount ${a.handle}: ${r.status} ${await r.text()}`) await stop(1) } } // ------------------------------------------------------------ the email /// Call `method` of the server, as `auth`'s session if given; answer its body. async function xrpc(method, body, auth) { const r = await fetch(`${url}/xrpc/${method}`, { method: 'POST', headers: { 'content-type': 'application/json', ...(auth ? { authorization: `Bearer ${auth}` } : {}) }, ...(body ? { body: JSON.stringify(body) } : {}) }) const text = await r.text() if (!r.ok) { console.error(`${method}: ${r.status} ${text}`) await stop(1) } return text ? JSON.parse(text) : {} } /// The next email to reach the SMTP server: its text part's token and its HTML part. async function nextEmail() { for (let t = 0; t < 200; t++) { const m = smtp.take().find((x) => !x.problem) if (m) { const { parts } = partsOf(m.data) const text = parts.find((p) => p.type === 'text/plain')?.text ?? '' return { token: /[A-Z2-7]{5}-[A-Z2-7]{5}/.exec(text)?.[0], html: parts.find((p) => p.type === 'text/html')?.text } } await new Promise((ok) => setTimeout(ok, 50)) } console.error('no email reached the SMTP server') await stop(1) } /// Ask for an email of `kind` as alice would; answer its HTML part. An /// update and the sign-in code are sent only for a confirmed email, so /// those confirm it first, and the sign-in code turns the email factor on. async function askEmail() { const [alice] = ACCOUNTS const { accessJwt } = await xrpc('com.atproto.server.createSession', { identifier: alice.handle, password: alice.password }) const confirm = async () => { await xrpc('com.atproto.server.requestEmailConfirmation', null, accessJwt) const { token } = await nextEmail() await xrpc('com.atproto.server.confirmEmail', { email: alice.email, token }, accessJwt) } if (kind === 'confirmEmail') await xrpc('com.atproto.server.requestEmailConfirmation', null, accessJwt) if (kind === 'resetPassword') await xrpc('com.atproto.server.requestPasswordReset', { email: alice.email }) if (kind === 'deleteAccount') await xrpc('com.atproto.server.requestAccountDelete', null, accessJwt) if (kind === 'plcOperation') await xrpc('com.atproto.identity.requestPlcOperationSignature', null, accessJwt) if (kind === 'updateEmail') { await confirm() await xrpc('com.atproto.server.requestEmailUpdate', null, accessJwt) } if (kind === 'signInAuthFactor') { await confirm() await xrpc('com.atproto.server.requestEmailUpdate', null, accessJwt) const { token } = await nextEmail() await xrpc('com.atproto.server.updateEmail', { email: alice.email, emailAuthFactor: true, token }, accessJwt) await fetch(`${url}/xrpc/com.atproto.server.createSession`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ identifier: alice.handle, password: alice.password }) }) } const { html } = await nextEmail() if (!html) { console.error('the email has no HTML part') await stop(1) } return html } const emailHtml = smtp ? await askEmail() : undefined // --------------------------------------------------------------- the PAR const b64u = (b) => Buffer.from(b).toString('base64url') const { subtle } = webcrypto const key = await subtle.generateKey({ name: 'ECDSA', namedCurve: 'P-256' }, true, ['sign', 'verify']) const { kty, crv, x, y } = await subtle.exportKey('jwk', key.publicKey) let nonce async function proof(htu) { const header = { typ: 'dpop+jwt', alg: 'ES256', jwk: { kty, crv, x, y } } const claims = { jti: b64u(randomBytes(16)), htm: 'POST', htu, iat: Math.floor(Date.now() / 1000), ...(nonce ? { nonce } : {}) } const input = `${b64u(JSON.stringify(header))}.${b64u(JSON.stringify(claims))}` return `${input}.${b64u(await subtle.sign({ name: 'ECDSA', hash: 'SHA-256' }, key.privateKey, Buffer.from(input)))}` } const REDIRECT = 'http://127.0.0.1/callback' const scope = value('--scope') ?? 'atproto transition:generic' const clientId = `http://localhost?${new URLSearchParams({ scope, redirect_uri: REDIRECT })}` async function par(hint) { const body = new URLSearchParams({ client_id: clientId, response_type: 'code', redirect_uri: REDIRECT, scope, state: b64u(randomBytes(12)), code_challenge: b64u(createHash('sha256').update(b64u(randomBytes(32))).digest()), code_challenge_method: 'S256', ...(hint ? { login_hint: hint } : {}) }) for (let attempt = 0; attempt < 2; attempt++) { const r = await fetch(`${url}/oauth/par`, { method: 'POST', headers: { 'content-type': 'application/x-www-form-urlencoded', dpop: await proof(`${url}/oauth/par`) }, body }) nonce = r.headers.get('dpop-nonce') ?? nonce const j = await r.json() if (r.status === 201) return `${url}/oauth/authorize?${new URLSearchParams({ client_id: clientId, request_uri: j.request_uri })}` if (j.error !== 'use_dpop_nonce') { console.error(`PAR: ${r.status} ${JSON.stringify(j)}`) await stop(1) } } } // ----------------------------------------------------------- the drawing const button = (page, name) => page.getByRole('button', { name, exact: true }) const textbox = (page, name) => page.getByRole('textbox', { name, exact: true }) const [alice, long] = ACCOUNTS async function signIn(page, who, { remember = false } = {}) { await textbox(page, 'Handle or email').fill(who.handle) await textbox(page, 'Password').fill(who.password) await page.getByRole('checkbox', { name: 'Remember this account on this device', exact: true }).setChecked(remember) const answered = page.waitForResponse((r) => r.url().includes('/~api/sign-in')) await button(page, 'Sign in').click() await answered } /// Chromium's virtual authenticator on `page`: a phone or laptop that keeps /// passkeys and verifies its user. async function authenticator(ctx, page) { const cdp = await ctx.newCDPSession(page) await cdp.send('WebAuthn.enable') await cdp.send('WebAuthn.addVirtualAuthenticator', { options: { protocol: 'ctap2', transport: 'internal', hasResidentKey: true, hasUserVerification: true, isUserVerified: true, automaticPresenceSimulation: true } }) } /// Bring `page` of `ctx` to the state, and answer when it shows. async function reach(ctx, page) { if (state === 'email') return page.setContent(emailHtml) await page.route((u) => u.hostname === '127.0.0.1' && u.pathname === '/callback', (r) => r.fulfill({ body: 'the client' })) if (state === 'error') return page.goto(`${url}/oauth/authorize?client_id=${encodeURIComponent('http://localhost')}`) if (state === 'add-passkey' || state === 'passkey-added') { await authenticator(ctx, page) const { accessJwt } = await xrpc('com.atproto.server.createSession', { identifier: alice.handle, password: alice.password }) const link = await xrpc('_passkeyAdd', { name: 'Laptop' }, accessJwt) await page.goto(link.url) if (state === 'add-passkey') return const answered = page.waitForResponse((r) => r.url().includes('/~api/passkey-register')) await button(page, 'Add passkey').click() await answered return page.getByRole('heading', { name: 'Passkey added', exact: true }).waitFor() } if (state === 'no-passkey') { // An authenticator holding no passkey: the browser gives none. await authenticator(ctx, page) await page.goto(await par()) await button(page, 'Sign in with a passkey').click() return page.getByRole('alert').waitFor() } if (state === 'choose') { for (const who of ACCOUNTS) { const p = await ctx.newPage() await p.goto(await par()) if (await button(p, 'Another account').count()) await button(p, 'Another account').click() await signIn(p, who, { remember: true }) await p.close() } return page.goto(await par()) } await page.goto(await par(flag('--hint') ? alice.handle : undefined)) if (state === 'sign-in') return if (state === 'wrong-password') return signIn(page, { ...alice, password: 'not-the-password' }) if (state === 'rate-limited') { await page.route('**/~api/sign-in', (r) => r.fulfill({ status: 429, headers: { 'retry-after': '600' }, contentType: 'application/json', body: '{"error":"invalid_request","error_description":"Too many"}' })) return signIn(page, alice) } if (state === 'email-code') { await page.route('**/~api/sign-in', (r) => r.fulfill({ status: 401, contentType: 'application/json', body: '{"error":"second_authentication_factor_required","error_description":"A code was sent"}' })) return signIn(page, alice) } if (state === 'busy') { await page.route('**/~api/sign-in', () => {}) await textbox(page, 'Handle or email').fill(alice.handle) await textbox(page, 'Password').fill(alice.password) await button(page, 'Sign in').click() return page.waitForTimeout(300) } await signIn(page, flag('--hint') ? alice : long) if (state === 'ended') { await page.route('**/~api/consent', (r) => r.fulfill({ status: 400, contentType: 'application/json', body: '{"error":"invalid_request","error_description":"gone"}' })) await button(page, 'Allow').click() } if (flag('--details')) for (const s of await page.locator('details summary').all()) await s.click() } const sizes = flag('--phone') ? ['phone'] : flag('--desktop') ? ['desktop'] : ['desktop', 'phone'] const schemeFor = (size) => (flag('--light') ? 'light' : flag('--dark') ? 'dark' : size === 'phone' ? 'dark' : 'light') const browser = await chromium.launch() let wide = false for (const size of sizes) { const scheme = schemeFor(size) const ctx = await browser.newContext(size === 'phone' ? { viewport: { width: 360, height: 740 }, isMobile: true, hasTouch: true, colorScheme: scheme } : { viewport: { width: 1200, height: 900 }, colorScheme: scheme }) const page = await ctx.newPage() const said = [] page.on('console', (m) => { if (/^Failed to load resource: /.test(m.text())) return said.push(`${m.type()}: ${m.text()}`) }) page.on('pageerror', (e) => said.push(`pageerror: ${e.message}`)) await reach(ctx, page) await page.waitForTimeout(300) const past = await page.evaluate((within) => { const w = window.innerWidth if (document.documentElement.scrollWidth <= w) return null const el = [...document.querySelectorAll(within)].find((e) => e.getBoundingClientRect().right > w + 0.5) return el ? `${el.tagName.toLowerCase()}${el.className ? `.${[...el.classList].join('.')}` : ''}: "${el.textContent.trim().slice(0, 60)}"` : 'something' }, state === 'email' ? 'body *' : 'main *') const file = join(out, `${kind ? `email-${kind}` : state}-${size}-${scheme}.png`) await page.screenshot({ path: file, fullPage: true }) console.log(file) if (past) { wide = true console.log(` wider than the screen (${size}): ${past}`) } for (const s of said) console.log(` console: ${s}`) await ctx.close() } await browser.close() await stop(wide ? 1 : 0)