@atproto/lex-password-session 0.0.0

package/src/lexicons/com/atproto/server/refreshSession.defs.ts

@@ -0,0 +1,43 @@
+/*
+ * THIS FILE WAS GENERATED BY "@atproto/lex". DO NOT EDIT.
+ */
+
+import { l } from '@atproto/lex-schema'
+
+const $nsid = 'com.atproto.server.refreshSession'
+
+export { $nsid }
+
+/** Refresh an authentication session. Requires auth using the 'refreshJwt' (not the 'accessJwt'). */
+const main =
+  /*#__PURE__*/
+  l.procedure(
+    $nsid,
+    /*#__PURE__*/ l.params(),
+    /*#__PURE__*/ l.payload(),
+    /*#__PURE__*/ l.jsonPayload({
+      accessJwt: /*#__PURE__*/ l.string(),
+      refreshJwt: /*#__PURE__*/ l.string(),
+      handle: /*#__PURE__*/ l.string({ format: 'handle' }),
+      did: /*#__PURE__*/ l.string({ format: 'did' }),
+      didDoc: /*#__PURE__*/ l.optional(/*#__PURE__*/ l.unknownObject()),
+      email: /*#__PURE__*/ l.optional(/*#__PURE__*/ l.string()),
+      emailConfirmed: /*#__PURE__*/ l.optional(/*#__PURE__*/ l.boolean()),
+      emailAuthFactor: /*#__PURE__*/ l.optional(/*#__PURE__*/ l.boolean()),
+      active: /*#__PURE__*/ l.optional(/*#__PURE__*/ l.boolean()),
+      status: /*#__PURE__*/ l.optional(/*#__PURE__*/ l.string()),
+    }),
+    ['AccountTakedown', 'InvalidToken', 'ExpiredToken'],
+  )
+export { main }
+
+export type Params = l.InferMethodParams<typeof main>
+export type Input = l.InferMethodInput<typeof main>
+export type InputBody = l.InferMethodInputBody<typeof main>
+export type Output = l.InferMethodOutput<typeof main>
+export type OutputBody = l.InferMethodOutputBody<typeof main>
+
+export const $lxm = /*#__PURE__*/ main.nsid,
+  $params = /*#__PURE__*/ main.parameters,
+  $input = /*#__PURE__*/ main.input,
+  $output = /*#__PURE__*/ main.output

package/src/lexicons/com/atproto/server/refreshSession.ts

@@ -0,0 +1,6 @@
+/*
+ * THIS FILE WAS GENERATED BY "@atproto/lex". DO NOT EDIT.
+ */
+
+export * from './refreshSession.defs.js'
+export * as $defs from './refreshSession.defs.js'

package/src/lexicons/com/atproto/server.ts

@@ -0,0 +1,9 @@
+/*
+ * THIS FILE WAS GENERATED BY "@atproto/lex". DO NOT EDIT.
+ */
+
+export * as createAccount from './server/createAccount.js'
+export * as createSession from './server/createSession.js'
+export * as deleteSession from './server/deleteSession.js'
+export * as getSession from './server/getSession.js'
+export * as refreshSession from './server/refreshSession.js'

package/src/lexicons/com/atproto.ts

@@ -0,0 +1,5 @@
+/*
+ * THIS FILE WAS GENERATED BY "@atproto/lex". DO NOT EDIT.
+ */
+
+export * as server from './atproto/server.js'

package/src/lexicons/com.ts

@@ -0,0 +1,5 @@
+/*
+ * THIS FILE WAS GENERATED BY "@atproto/lex". DO NOT EDIT.
+ */
+
+export * as atproto from './com/atproto.js'

package/src/lexicons/index.ts

@@ -0,0 +1,5 @@
+/*
+ * THIS FILE WAS GENERATED BY "@atproto/lex". DO NOT EDIT.
+ */
+
+export * as com from './com.js'

package/src/password-session-utils.test.ts

@@ -0,0 +1,177 @@
+/* eslint-disable @typescript-eslint/no-namespace */
+
+import { describe, expect, it } from 'vitest'
+import { DidString, HandleString } from '@atproto/lex-schema'
+import { LexServerAuthError } from '@atproto/lex-server'
+
+const randomString = () =>
+  Math.random().toString(36).substring(2, 10) +
+  Math.random().toString(36).substring(2, 10)
+
+export class Session {
+  active = true
+  accessJwt = randomString()
+  refreshJwt = randomString()
+  constructor(readonly identifier: string) {}
+  get did(): DidString {
+    return `did:example:${this.identifier}`
+  }
+  get handle(): HandleString {
+    return `${this.identifier}.example`
+  }
+  get email(): string {
+    return `${this.identifier}@example.com`
+  }
+  rotate() {
+    this.accessJwt = randomString()
+    this.refreshJwt = randomString()
+    return this
+  }
+  destroy() {
+    this.active = false
+  }
+}
+
+describe('Session', () => {
+  it('generates DID and handle from identifier', async () => {
+    const session = new Session('alice')
+    expect(session.did).toBe('did:example:alice')
+    expect(session.handle).toBe('alice.example')
+  })
+
+  it('rotates tokens', async () => {
+    const session = new Session('alice')
+    const oldAccess = session.accessJwt
+    const oldRefresh = session.refreshJwt
+    session.rotate()
+    expect(session.accessJwt).not.toBe(oldAccess)
+    expect(session.refreshJwt).not.toBe(oldRefresh)
+  })
+
+  it('destroys session', async () => {
+    const session = new Session('alice')
+    expect(session.active).toBe(true)
+    session.destroy()
+    expect(session.active).toBe(false)
+  })
+})
+
+export class AuthVerifier {
+  sessions: Session[] = []
+
+  async create(credentials: {
+    identifier: string
+    password: string
+    authFactorToken?: string
+  }) {
+    if (!credentials.identifier || credentials.password !== 'password123') {
+      throw new LexServerAuthError(
+        'AuthenticationRequired',
+        'Invalid identifier',
+      )
+    }
+    if (credentials.authFactorToken !== '2fa-token') {
+      throw new LexServerAuthError(
+        'AuthFactorTokenRequired',
+        '2FA token is required',
+      )
+    }
+    const session = new Session(credentials.identifier)
+    this.sessions.push(session)
+    return session
+  }
+
+  async findBy(predicate: (s: Session) => boolean) {
+    return this.sessions.find((s) => s.active && predicate(s))
+  }
+
+  accessStrategy = async ({ request }: { request: Request }) => {
+    const auth = request.headers.get('authorization')
+    const token = auth?.startsWith('Bearer ') && auth.slice(7)
+    const session = await this.findBy((s) => s.accessJwt === token)
+    if (!session) {
+      throw new LexServerAuthError('AuthenticationRequired', 'Invalid token', {
+        Bearer: { realm: 'access token' },
+      })
+    }
+    return { session }
+  }
+
+  refreshStrategy = async ({ request }: { request: Request }) => {
+    const auth = request.headers.get('authorization')
+    const token = auth?.startsWith('Bearer ') && auth.slice(7)
+    const session = await this.findBy((s) => s.refreshJwt === token)
+    if (!session) {
+      throw new LexServerAuthError('ExpiredToken', 'Invalid token', {
+        Bearer: { realm: 'refresh token' },
+      })
+    }
+    return { session }
+  }
+}
+
+describe('AuthVerifier', () => {
+  it('creates session with valid credentials', async () => {
+    const verifier = new AuthVerifier()
+    const session = await verifier.create({
+      identifier: 'alice',
+      password: 'password123',
+      authFactorToken: '2fa-token',
+    })
+    expect(session.identifier).toBe('alice')
+  })
+
+  it('rejects invalid credentials', async () => {
+    const verifier = new AuthVerifier()
+    await expect(
+      verifier.create({
+        identifier: 'alice',
+        password: 'wrong-password',
+      }),
+    ).rejects.toMatchObject({
+      error: 'AuthenticationRequired',
+    })
+  })
+
+  it('rejects missing 2fa token', async () => {
+    const verifier = new AuthVerifier()
+    await expect(
+      verifier.create({
+        identifier: 'alice',
+        password: 'password123',
+      }),
+    ).rejects.toMatchObject({
+      error: 'AuthFactorTokenRequired',
+    })
+  })
+
+  it('finds session by access token', async () => {
+    const verifier = new AuthVerifier()
+    const session = await verifier.create({
+      identifier: 'alice',
+      password: 'password123',
+      authFactorToken: '2fa-token',
+    })
+    const found = await verifier.accessStrategy({
+      request: new Request('http://example.com', {
+        headers: { authorization: `Bearer ${session.accessJwt}` },
+      }),
+    })
+    expect(found.session).toBe(session)
+  })
+
+  it('finds session by refresh token', async () => {
+    const verifier = new AuthVerifier()
+    const session = await verifier.create({
+      identifier: 'alice',
+      password: 'password123',
+      authFactorToken: '2fa-token',
+    })
+    const found = await verifier.refreshStrategy({
+      request: new Request('http://example.com', {
+        headers: { authorization: `Bearer ${session.refreshJwt}` },
+      }),
+    })
+    expect(found.session).toBe(session)
+  })
+})

package/src/password-session.test.ts

@@ -0,0 +1,416 @@
+/* eslint-disable @typescript-eslint/no-namespace */
+
+import { afterAll, assert, beforeAll, describe, expect, it, vi } from 'vitest'
+import { Client, LexRpcResponseError } from '@atproto/lex-client'
+import { l } from '@atproto/lex-schema'
+import { LexRouter, LexServerAuthError } from '@atproto/lex-server'
+import { Server, serve } from '@atproto/lex-server/nodejs'
+import { LexAuthFactorError } from './error.js'
+import { com } from './lexicons/index.js'
+import { AuthVerifier } from './password-session-utils.test.js'
+import {
+  PasswordSession,
+  PasswordSessionOptions,
+  SessionData,
+} from './password-session.js'
+
+const defaultOptions: Partial<PasswordSessionOptions> = {
+  onUpdateFailure: async (session, cause) => {
+    throw new Error('Should not fail to refresh session', { cause })
+  },
+  onDeleteFailure: async (session, cause) => {
+    throw new Error('Should not fail to delete session', { cause })
+  },
+}
+
+// Example app lexicon
+namespace app {
+  export namespace example {
+    export namespace customMethod {
+      export const main = l.procedure(
+        'app.example.customMethod',
+        l.params(),
+        l.jsonPayload({ message: l.string() }),
+        l.jsonPayload({
+          message: l.string(),
+          did: l.string({ format: 'did' }),
+        }),
+      )
+    }
+
+    export namespace expiredToken {
+      export const main = l.query(
+        'app.example.expiredToken',
+        l.params(),
+        l.payload(),
+      )
+    }
+  }
+}
+
+describe(PasswordSession, () => {
+  let entrywayServer: Server
+  let entrywayOrigin: string
+
+  let pdsServer: Server
+  let pdsOrigin: string
+
+  beforeAll(async () => {
+    const authVerifier = new AuthVerifier()
+
+    const entrywayRouter = new LexRouter()
+      .add(com.atproto.server.createSession, async ({ input }) => {
+        const session = await authVerifier.create(input.body)
+
+        const body: com.atproto.server.createSession.OutputBody = {
+          accessJwt: session.accessJwt,
+          refreshJwt: session.refreshJwt,
+
+          did: session.did,
+          didDoc: {
+            '@context': 'https://w3.org/ns/did/v1',
+            id: session.did,
+            service: [
+              {
+                id: `${session.did}#atproto_pds`,
+                type: 'AtprotoPersonalDataServer',
+                serviceEndpoint: pdsUrl,
+              },
+            ],
+          },
+          handle: session.handle,
+        }
+
+        return { body }
+      })
+      .add(com.atproto.server.getSession, {
+        auth: authVerifier.accessStrategy,
+        handler: async ({ credentials: { session } }) => {
+          const body: com.atproto.server.getSession.OutputBody = {
+            did: session.did,
+            didDoc: {
+              '@context': 'https://w3.org/ns/did/v1',
+              id: session.did,
+              service: [
+                {
+                  id: `${session.did}#atproto_pds`,
+                  type: 'AtprotoPersonalDataServer',
+                  serviceEndpoint: pdsOrigin,
+                },
+              ],
+            },
+            handle: session.handle,
+            email: session.email,
+            emailConfirmed: true,
+            emailAuthFactor: false,
+            active: true,
+            status: 'active',
+          }
+
+          return { body }
+        },
+      })
+      .add(com.atproto.server.refreshSession, {
+        auth: authVerifier.refreshStrategy,
+        handler: async ({ credentials: { session } }) => {
+          await session.rotate()
+
+          // Note, we omit email and didDoc here to test that they are properly
+          // fetched via getSession in the agent
+          const body: com.atproto.server.refreshSession.OutputBody = {
+            accessJwt: session.accessJwt,
+            refreshJwt: session.refreshJwt,
+
+            did: session.did,
+            didDoc: undefined,
+            handle: session.handle,
+
+            email: undefined,
+            emailConfirmed: undefined,
+          }
+
+          return { body }
+        },
+      })
+      .add(com.atproto.server.deleteSession, {
+        auth: authVerifier.refreshStrategy,
+        handler: async ({ credentials: { session } }) => {
+          await session.destroy()
+          return {}
+        },
+      })
+
+    entrywayServer = await serve(entrywayRouter)
+    const { port } = entrywayServer.address() as { port: number }
+    entrywayOrigin = `http://localhost:${port}`
+
+    const pdsRouter = new LexRouter()
+      .add(app.example.customMethod, {
+        auth: authVerifier.accessStrategy,
+        handler: async ({ input, credentials: { session } }) => {
+          return { body: { message: input.body.message, did: session.did } }
+        },
+      })
+      .add(app.example.expiredToken, async () => {
+        throw new LexServerAuthError('ExpiredToken', 'Token expired')
+      })
+
+    pdsServer = await serve(pdsRouter)
+    const { port: pdsPort } = pdsServer.address() as { port: number }
+    pdsOrigin = `http://localhost:${pdsPort}`
+    const pdsUrl = pdsOrigin
+  })
+
+  afterAll(async () => {
+    entrywayServer.close()
+    pdsServer.close()
+  })
+
+  it('fails with invalid credentials', async () => {
+    const onDeleted: PasswordSessionOptions['onDeleted'] = vi.fn()
+    const onUpdated: PasswordSessionOptions['onUpdated'] = vi.fn()
+
+    await expect(
+      PasswordSession.create({
+        ...defaultOptions,
+        service: entrywayOrigin,
+        identifier: 'alice',
+        password: 'wrong-password',
+        onDeleted,
+        onUpdated,
+      }),
+    ).rejects.toMatchObject({
+      success: false,
+      status: 401,
+      error: 'AuthenticationRequired',
+    })
+
+    expect(onDeleted).not.toHaveBeenCalled()
+    expect(onUpdated).not.toHaveBeenCalled()
+  })
+
+  it('requires 2fa', async () => {
+    const onDeleted: PasswordSessionOptions['onDeleted'] = vi.fn()
+    const onUpdated: PasswordSessionOptions['onUpdated'] = vi.fn()
+
+    const result = await PasswordSession.create({
+      ...defaultOptions,
+      service: entrywayOrigin,
+      identifier: 'alice',
+      password: 'password123',
+      onDeleted,
+      onUpdated,
+    }).then(
+      () => {
+        throw new Error('Expected to fail')
+      },
+      (err: unknown) => err,
+    )
+
+    assert(result instanceof LexAuthFactorError)
+    expect(result.error).toBe('AuthFactorTokenRequired')
+    expect(onDeleted).not.toHaveBeenCalled()
+    expect(onUpdated).not.toHaveBeenCalled()
+  })
+
+  it('logs in', async () => {
+    const onDeleted: PasswordSessionOptions['onDeleted'] = vi.fn()
+    const onUpdated: PasswordSessionOptions['onUpdated'] = vi.fn()
+
+    const session = await PasswordSession.create({
+      ...defaultOptions,
+      service: entrywayOrigin,
+      identifier: 'alice',
+      password: 'password123',
+      authFactorToken: '2fa-token',
+      onDeleted,
+      onUpdated,
+    })
+
+    expect(onUpdated).toHaveBeenCalledTimes(1)
+
+    const client = new Client(session)
+
+    await expect(
+      client.call(app.example.customMethod, { message: 'hello' }),
+    ).resolves.toMatchObject({
+      message: 'hello',
+      did: 'did:example:alice',
+    })
+
+    await expect(
+      client.call(app.example.customMethod, { message: 'world' }),
+    ).resolves.toMatchObject({
+      message: 'world',
+      did: 'did:example:alice',
+    })
+
+    expect(onDeleted).not.toHaveBeenCalled()
+
+    await session.logout()
+
+    expect(onDeleted).toHaveBeenCalled()
+
+    await expect(
+      client.call(app.example.customMethod, { message: 'hello' }),
+    ).rejects.toThrow('Logged out')
+  })
+
+  it('fails to perform unauthenticated call', async () => {
+    const client = new Client(pdsOrigin)
+    const result = await client.xrpcSafe(app.example.customMethod, {
+      body: { message: 'hello' },
+    })
+
+    assert(result.success === false)
+    assert(result instanceof LexRpcResponseError)
+    expect(result).toMatchObject({
+      success: false,
+      status: 401,
+      error: 'AuthenticationRequired',
+    })
+    expect(result.headers.get('www-authenticate')).toBe(
+      'Bearer realm="access token"',
+    )
+  })
+
+  it('refreshes expired token', async () => {
+    const onDeleted: PasswordSessionOptions['onDeleted'] = vi.fn()
+    const onUpdated: PasswordSessionOptions['onUpdated'] = vi.fn()
+
+    const session = await PasswordSession.create({
+      ...defaultOptions,
+      service: entrywayOrigin,
+      identifier: 'bob',
+      password: 'password123',
+      authFactorToken: '2fa-token',
+      onUpdated,
+      onDeleted,
+    })
+
+    const client = new Client(session)
+
+    await expect(
+      client.call(app.example.customMethod, { message: 'before' }),
+    ).resolves.toMatchObject({
+      message: 'before',
+      did: 'did:example:bob',
+    })
+
+    expect(onUpdated).toHaveBeenCalledTimes(1)
+
+    await expect(client.call(app.example.expiredToken)).rejects.toThrow(
+      'Token expired',
+    )
+
+    expect(onUpdated).toHaveBeenCalledTimes(2)
+    expect(onUpdated).toHaveBeenLastCalledWith(
+      expect.objectContaining({
+        service: entrywayOrigin,
+
+        accessJwt: expect.any(String),
+        refreshJwt: expect.any(String),
+
+        email: expect.stringContaining('@'),
+        emailConfirmed: true,
+        emailAuthFactor: false,
+        handle: 'bob.example',
+        did: 'did:example:bob',
+        didDoc: expect.objectContaining({ id: 'did:example:bob' }),
+      }),
+    )
+
+    await expect(
+      client.call(app.example.customMethod, { message: 'after' }),
+    ).resolves.toMatchObject({
+      message: 'after',
+      did: 'did:example:bob',
+    })
+  })
+
+  it('restores session from storage', async () => {
+    const onDeleted: PasswordSessionOptions['onDeleted'] = vi.fn()
+    const onUpdated: PasswordSessionOptions['onUpdated'] = vi.fn()
+
+    const initialAgent = await PasswordSession.create({
+      ...defaultOptions,
+      service: entrywayOrigin,
+      identifier: 'carla',
+      password: 'password123',
+      authFactorToken: '2fa-token',
+      onUpdated,
+      onDeleted,
+    })
+
+    expect(initialAgent.did).toEqual('did:example:carla')
+    expect(onDeleted).toHaveBeenCalledTimes(0)
+    expect(onUpdated).toHaveBeenCalledTimes(1)
+    expect(onUpdated).toHaveBeenCalledWith(
+      expect.objectContaining({
+        accessJwt: expect.any(String),
+        refreshJwt: expect.any(String),
+      }),
+    )
+
+    const sessionData = initialAgent.session
+
+    const resumedAgent = await PasswordSession.resume(sessionData, {
+      ...defaultOptions,
+      onUpdated,
+      onDeleted,
+    })
+
+    expect(resumedAgent.did).toEqual('did:example:carla')
+    expect(onDeleted).toHaveBeenCalledTimes(0)
+    expect(onUpdated).toHaveBeenCalledTimes(2)
+
+    // The initial session was refreshed. The data it contains is now invalid.
+    await expect(initialAgent.refresh()).rejects.toMatchObject({
+      success: false,
+      error: 'ExpiredToken',
+      status: 401,
+    })
+
+    expect(onDeleted).toHaveBeenCalledTimes(1)
+
+    const client = new Client(resumedAgent)
+    await expect(
+      client.call(app.example.customMethod, { message: 'resume' }),
+    ).resolves.toMatchObject({
+      message: 'resume',
+      did: 'did:example:carla',
+    })
+
+    expect(onDeleted).toHaveBeenCalledTimes(1)
+    expect(onUpdated).toHaveBeenCalledTimes(2)
+
+    await resumedAgent.logout()
+
+    expect(onDeleted).toHaveBeenCalledTimes(2)
+    expect(onUpdated).toHaveBeenCalledTimes(2)
+  })
+
+  it('silently ignores expected logout errors', async () => {
+    let sessionData: SessionData | null = null
+
+    const session = await PasswordSession.create({
+      ...defaultOptions,
+      service: entrywayOrigin,
+      identifier: 'dave',
+      password: 'password123',
+      authFactorToken: '2fa-token',
+      onUpdated: (data) => {
+        sessionData = structuredClone(data)
+      },
+      onDeleted: () => {},
+    })
+
+    assert(sessionData)
+
+    await session.logout()
+    await session.logout()
+
+    await PasswordSession.delete(sessionData)
+    await PasswordSession.delete(sessionData)
+  })
+})