@atproto/space 0.0.0-spaces-alpha-20260818022935

package/tests/credential.test.ts

@@ -0,0 +1,323 @@
+import { beforeAll, describe, expect, it, vi } from 'vitest'
+import { type Keypair, Secp256k1Keypair } from '@atproto/crypto'
+import {
+  SPACE_TOKEN_TYPES,
+  SpaceTokenError,
+  createSpaceToken,
+  parseSpaceToken,
+  verifySpaceToken,
+} from '../src/index.js'
+
+const SPACE = 'at://did:example:space/space/app.bsky.group/test'
+const USER = 'did:example:alice'
+const AUTHORITY = 'did:example:space'
+const SPACE_HOST = `${AUTHORITY}#atproto_space_host`
+const CLIENT_ID = 'https://app.example.com/client-metadata.json'
+const DPOP_JKT = '0ZcOCORZNYy-DWpqq30jZyJGHTN0d2HglBV3uiguA4I'
+
+/** Swap a token's `typ` header, leaving its payload and signature alone. */
+const retypeToken = (jwt: string, typ: string): string => {
+  const [headerB64, payloadB64, sigB64] = jwt.split('.')
+  const header = JSON.parse(Buffer.from(headerB64, 'base64url').toString())
+  const retyped = Buffer.from(JSON.stringify({ ...header, typ })).toString(
+    'base64url',
+  )
+  return `${retyped}.${payloadB64}.${sigB64}`
+}
+
+describe('space tokens', () => {
+  let userKey: Keypair
+  let authorityKey: Keypair
+  let clientKey: Keypair
+
+  beforeAll(async () => {
+    ;[userKey, authorityKey, clientKey] = await Promise.all([
+      Secp256k1Keypair.create(),
+      Secp256k1Keypair.create(),
+      Secp256k1Keypair.create(),
+    ])
+  })
+
+  const getKey = (keypair: Keypair) => () => keypair.did()
+
+  describe('delegation token', () => {
+    const create = () =>
+      createSpaceToken(
+        'delegation',
+        { iss: USER, sub: SPACE, aud: SPACE_HOST },
+        userKey,
+      )
+
+    it('round-trips', async () => {
+      const { header, payload } = await verifySpaceToken(
+        'delegation',
+        await create(),
+        { getSigningKey: getKey(userKey), aud: SPACE_HOST, sub: SPACE },
+      )
+      expect(header.typ).toBe('atproto-space-delegation+jwt')
+      expect(header.kid).toBe('#atproto')
+      expect(header.alg).toBe(userKey.jwtAlg)
+      expect(payload.iss).toBe(USER)
+      expect(payload.sub).toBe(SPACE)
+      expect(payload.aud).toBe(SPACE_HOST)
+      expect(payload.exp - payload.iat).toBe(60)
+      expect(payload.jti).toMatch(/^[0-9a-f]{32}$/)
+    })
+
+    it('requires an aud at mint time', async () => {
+      await expect(
+        createSpaceToken('delegation', { iss: USER, sub: SPACE }, userKey),
+      ).rejects.toThrow(/requires an "aud"/)
+    })
+
+    it('is rejected by an authority it was not addressed to', async () => {
+      const jwt = await create()
+      await expect(
+        verifySpaceToken('delegation', jwt, {
+          getSigningKey: getKey(userKey),
+          aud: 'did:example:other#atproto_space_host',
+        }),
+      ).rejects.toMatchObject({ code: 'BadJwtAudience' })
+    })
+
+    it('is rejected for a space other than its subject', async () => {
+      const jwt = await create()
+      await expect(
+        verifySpaceToken('delegation', jwt, {
+          getSigningKey: getKey(userKey),
+          aud: SPACE_HOST,
+          sub: 'at://did:example:space/space/app.bsky.group/other',
+        }),
+      ).rejects.toMatchObject({ code: 'BadJwtSub' })
+    })
+
+    it('is rejected when signed by the wrong key', async () => {
+      const jwt = await create()
+      await expect(
+        verifySpaceToken('delegation', jwt, {
+          getSigningKey: getKey(authorityKey),
+          aud: SPACE_HOST,
+        }),
+      ).rejects.toMatchObject({ code: 'BadJwtSignature' })
+    })
+
+    it('is rejected when its type is wrong', async () => {
+      const jwt = await create()
+      await expect(
+        verifySpaceToken('credential', jwt, {
+          getSigningKey: getKey(userKey),
+        }),
+      ).rejects.toMatchObject({ code: 'BadJwtType' })
+    })
+  })
+
+  describe('space credential', () => {
+    const create = (opts?: { expiresInSec?: number; kid?: string }) =>
+      createSpaceToken(
+        'credential',
+        { iss: AUTHORITY, sub: SPACE, dpopJkt: DPOP_JKT, ...opts },
+        authorityKey,
+      )
+
+    it('round-trips, defaults to 2h, and carries no aud', async () => {
+      const { header, payload } = await verifySpaceToken(
+        'credential',
+        await create(),
+        { getSigningKey: getKey(authorityKey), sub: SPACE },
+      )
+      expect(header.typ).toBe('atproto-space-credential+jwt')
+      expect(header.kid).toBe('#atproto')
+      expect(payload.iss).toBe(AUTHORITY)
+      expect(payload.aud).toBeUndefined()
+      expect(payload.exp - payload.iat).toBe(7200)
+    })
+
+    it('is bound to the requested DPoP key', async () => {
+      const { payload } = await verifySpaceToken('credential', await create(), {
+        getSigningKey: getKey(authorityKey),
+      })
+      expect(payload.cnf?.jkt).toBe(DPOP_JKT)
+    })
+
+    it('requires a dpopJkt at mint time', async () => {
+      await expect(
+        createSpaceToken(
+          'credential',
+          { iss: AUTHORITY, sub: SPACE },
+          authorityKey,
+        ),
+      ).rejects.toThrow(/requires a "dpopJkt"/)
+    })
+
+    it('is rejected when it carries no binding', async () => {
+      const unbound = await createSpaceToken(
+        'delegation',
+        { iss: AUTHORITY, sub: SPACE, aud: SPACE_HOST },
+        authorityKey,
+      )
+      const forgedTyp = retypeToken(unbound, SPACE_TOKEN_TYPES.credential.typ)
+      expect(() => parseSpaceToken('credential', forgedTyp)).toThrow(
+        /missing token "cnf.jkt"/,
+      )
+    })
+
+    it('passes iss and kid to the key resolver', async () => {
+      const getSigningKey = vi.fn(() => authorityKey.did())
+      await verifySpaceToken('credential', await create(), { getSigningKey })
+      expect(getSigningKey).toHaveBeenCalledWith(AUTHORITY, '#atproto', false)
+    })
+
+    it('honours a kid override for authorities with a dedicated space key', async () => {
+      const getSigningKey = vi.fn(() => authorityKey.did())
+      const jwt = await create({ kid: '#atproto_space' })
+      await verifySpaceToken('credential', jwt, { getSigningKey })
+      expect(getSigningKey).toHaveBeenCalledWith(
+        AUTHORITY,
+        '#atproto_space',
+        false,
+      )
+    })
+
+    it('retries with a freshly resolved key when the signing key has rotated', async () => {
+      const rotatedKey = await Secp256k1Keypair.create()
+      const jwt = await createSpaceToken(
+        'credential',
+        { iss: AUTHORITY, sub: SPACE, dpopJkt: DPOP_JKT },
+        rotatedKey,
+      )
+      // First resolution returns the stale key, the retry the rotated one.
+      const getSigningKey = vi
+        .fn()
+        .mockResolvedValueOnce(authorityKey.did())
+        .mockResolvedValueOnce(rotatedKey.did())
+
+      const { payload } = await verifySpaceToken('credential', jwt, {
+        getSigningKey,
+      })
+      expect(payload.iss).toBe(AUTHORITY)
+      expect(getSigningKey).toHaveBeenNthCalledWith(
+        1,
+        AUTHORITY,
+        '#atproto',
+        false,
+      )
+      expect(getSigningKey).toHaveBeenNthCalledWith(
+        2,
+        AUTHORITY,
+        '#atproto',
+        true,
+      )
+    })
+
+    it('does not retry when the resolved key is unchanged', async () => {
+      const otherKey = await Secp256k1Keypair.create()
+      const jwt = await createSpaceToken(
+        'credential',
+        { iss: AUTHORITY, sub: SPACE, dpopJkt: DPOP_JKT },
+        otherKey,
+      )
+      const getSigningKey = vi.fn(() => authorityKey.did())
+      await expect(
+        verifySpaceToken('credential', jwt, { getSigningKey }),
+      ).rejects.toMatchObject({ code: 'BadJwtSignature' })
+      expect(getSigningKey).toHaveBeenCalledTimes(2)
+    })
+
+    it('rejects an expired credential', async () => {
+      const jwt = await create({ expiresInSec: 1 })
+      vi.useFakeTimers()
+      try {
+        vi.setSystemTime(Date.now() + 60_000)
+        await expect(
+          verifySpaceToken('credential', jwt, {
+            getSigningKey: getKey(authorityKey),
+          }),
+        ).rejects.toMatchObject({ code: 'JwtExpired' })
+      } finally {
+        vi.useRealTimers()
+      }
+    })
+
+    it('tolerates small clock skew', async () => {
+      const jwt = await create({ expiresInSec: 1 })
+      vi.useFakeTimers()
+      try {
+        // 2s past exp — inside the 5s skew allowance.
+        vi.setSystemTime(Date.now() + 3_000)
+        await expect(
+          verifySpaceToken('credential', jwt, {
+            getSigningKey: getKey(authorityKey),
+          }),
+        ).resolves.toBeTruthy()
+      } finally {
+        vi.useRealTimers()
+      }
+    })
+  })
+
+  describe('client attestation', () => {
+    const create = () =>
+      createSpaceToken(
+        'clientAttestation',
+        { iss: CLIENT_ID, sub: CLIENT_ID, aud: SPACE_HOST, kid: 'key-1' },
+        clientKey,
+      )
+
+    it('parses without needing a key', async () => {
+      const { header, payload } = parseSpaceToken(
+        'clientAttestation',
+        await create(),
+      )
+      expect(header.typ).toBe('atproto-client-attestation+jwt')
+      expect(header.kid).toBe('key-1')
+      expect(payload.iss).toBe(CLIENT_ID)
+      expect(payload.sub).toBe(CLIENT_ID)
+      expect(payload.aud).toBe(SPACE_HOST)
+    })
+
+    it('requires iss and sub to both be the client_id', async () => {
+      const jwt = await createSpaceToken(
+        'clientAttestation',
+        { iss: CLIENT_ID, sub: 'https://other.example/x', aud: SPACE_HOST },
+        clientKey,
+      )
+      expect(() => parseSpaceToken('clientAttestation', jwt)).toThrow(
+        /must both be the client_id/,
+      )
+    })
+
+    it('verifies against the client key when one is resolvable', async () => {
+      const { payload } = await verifySpaceToken(
+        'clientAttestation',
+        await create(),
+        { getSigningKey: getKey(clientKey), aud: SPACE_HOST },
+      )
+      expect(payload.iss).toBe(CLIENT_ID)
+    })
+  })
+
+  describe('malformed tokens', () => {
+    it.each([
+      ['not a jwt', 'nope'],
+      ['too few parts', 'aaa.bbb'],
+      ['bad base64 header', '!!!.e30.c2ln'],
+    ])('rejects %s', (_name, jwt) => {
+      expect(() => parseSpaceToken('credential', jwt)).toThrow(SpaceTokenError)
+    })
+
+    it('rejects a token missing required claims', async () => {
+      const header = Buffer.from(
+        JSON.stringify({
+          alg: 'ES256K',
+          typ: SPACE_TOKEN_TYPES.credential.typ,
+        }),
+      ).toString('base64url')
+      const payload = Buffer.from(JSON.stringify({ iss: AUTHORITY })).toString(
+        'base64url',
+      )
+      expect(() =>
+        parseSpaceToken('credential', `${header}.${payload}.c2ln`),
+      ).toThrow(/missing token "sub"/)
+    })
+  })
+})

package/tests/dpop.test.ts

@@ -0,0 +1,234 @@
+import { beforeAll, describe, expect, it, vi } from 'vitest'
+import { sha256 } from '@atproto/crypto'
+import { JoseKey } from '@atproto/jwk-jose'
+import { toBase64 } from '@atproto/lex-data'
+import {
+  MAX_PROOF_AGE_SEC,
+  createDpopProof,
+  dpopJktForKey,
+  verifyDpopProof,
+} from '../src/index.js'
+
+const CREDENTIAL = 'eyJ0eXAiOiJhdHByb3RvLXNwYWNlLWNyZWRlbnRpYWwrand0'
+const HTU = 'https://pds.example.com/xrpc/com.atproto.space.getRepo'
+const HTM = 'GET'
+const EXCHANGE_HTU =
+  'https://space.example.com/xrpc/com.atproto.space.getSpaceCredential'
+
+const athFor = async (credential: string): Promise<string> =>
+  toBase64(await sha256(credential), 'base64url')
+
+describe('DPoP proofs', () => {
+  let key: JoseKey
+  let otherKey: JoseKey
+
+  beforeAll(async () => {
+    ;[key, otherKey] = await Promise.all([
+      JoseKey.generate(['ES256']),
+      JoseKey.generate(['ES256']),
+    ])
+  })
+
+  const verifyAgainst = (
+    proof: string,
+    overrides: Partial<Parameters<typeof verifyDpopProof>[1]> = {},
+  ) =>
+    verifyDpopProof(proof, {
+      htm: HTM,
+      htu: HTU,
+      credential: CREDENTIAL,
+      jkt: overrides.jkt ?? '',
+      ...overrides,
+    })
+
+  it('round-trips a proof for the request it was minted for', async () => {
+    const jkt = await dpopJktForKey(key)
+    const proof = await createDpopProof(key, {
+      htm: HTM,
+      htu: HTU,
+      credential: CREDENTIAL,
+    })
+
+    const verified = await verifyAgainst(proof, { jkt })
+    expect(verified.jkt).toBe(jkt)
+    expect(verified.htm).toBe(HTM)
+    expect(verified.htu).toBe(HTU)
+    expect(verified.jti).toBeTruthy()
+  })
+
+  it('derives a key binding from a credential exchange proof without ath', async () => {
+    const proof = await createDpopProof(key, {
+      htm: 'POST',
+      htu: EXCHANGE_HTU,
+    })
+
+    await expect(
+      verifyDpopProof(proof, { htm: 'POST', htu: EXCHANGE_HTU }),
+    ).resolves.toMatchObject({ jkt: await dpopJktForKey(key) })
+  })
+
+  it('refuses ath on a credential exchange proof', async () => {
+    const proof = await createDpopProof(key, {
+      htm: 'POST',
+      htu: EXCHANGE_HTU,
+      credential: CREDENTIAL,
+    })
+
+    await expect(
+      verifyDpopProof(proof, { htm: 'POST', htu: EXCHANGE_HTU }),
+    ).rejects.toThrow(/"ath" must be omitted/)
+  })
+
+  it('mints a distinct jti per proof, so a verifier can reject replays', async () => {
+    const opts = { htm: HTM, htu: HTU, credential: CREDENTIAL }
+    const first = await verifyAgainst(await createDpopProof(key, opts), {
+      jkt: await dpopJktForKey(key),
+    })
+    const second = await verifyAgainst(await createDpopProof(key, opts), {
+      jkt: await dpopJktForKey(key),
+    })
+    expect(first.jti).not.toBe(second.jti)
+  })
+
+  it('strips query and fragment from htu, on both sides', async () => {
+    const proof = await createDpopProof(key, {
+      htm: HTM,
+      htu: `${HTU}?space=at%3A%2F%2Fdid%3Aexample%3Aspace&repo=did%3Aexample%3Abob`,
+      credential: CREDENTIAL,
+    })
+    const verified = await verifyAgainst(proof, {
+      jkt: await dpopJktForKey(key),
+      htu: `${HTU}?space=something&repo=else`,
+    })
+    expect(verified.htu).toBe(HTU)
+  })
+
+  it('refuses a proof signed by a key the credential is not bound to', async () => {
+    const proof = await createDpopProof(otherKey, {
+      htm: HTM,
+      htu: HTU,
+      credential: CREDENTIAL,
+    })
+    await expect(
+      verifyAgainst(proof, { jkt: await dpopJktForKey(key) }),
+    ).rejects.toMatchObject({ code: 'DpopKeyMismatch' })
+  })
+
+  it('refuses a proof addressed to another host', async () => {
+    const proof = await createDpopProof(key, {
+      htm: HTM,
+      htu: 'https://other-pds.example.com/xrpc/com.atproto.space.getRepo',
+      credential: CREDENTIAL,
+    })
+    await expect(
+      verifyAgainst(proof, { jkt: await dpopJktForKey(key) }),
+    ).rejects.toThrow(/"htu" does not match/)
+  })
+
+  it('refuses a proof minted for another method', async () => {
+    const proof = await createDpopProof(key, {
+      htm: 'POST',
+      htu: HTU,
+      credential: CREDENTIAL,
+    })
+    await expect(
+      verifyAgainst(proof, { jkt: await dpopJktForKey(key) }),
+    ).rejects.toThrow(/"htm" does not match/)
+  })
+
+  it('refuses a proof paired with a different credential', async () => {
+    const proof = await createDpopProof(key, {
+      htm: HTM,
+      htu: HTU,
+      credential: 'a-different-credential',
+    })
+    await expect(
+      verifyAgainst(proof, { jkt: await dpopJktForKey(key) }),
+    ).rejects.toThrow(/"ath" does not match/)
+  })
+
+  it('refuses a stale proof, as expired rather than unverifiable', async () => {
+    const proof = await createDpopProof(key, {
+      htm: HTM,
+      htu: HTU,
+      credential: CREDENTIAL,
+    })
+    const jkt = await dpopJktForKey(key)
+
+    vi.useFakeTimers()
+    try {
+      vi.setSystemTime(Date.now() + (MAX_PROOF_AGE_SEC + 60) * 1000)
+      await expect(verifyAgainst(proof, { jkt })).rejects.toMatchObject({
+        code: 'DpopProofExpired',
+      })
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  describe('clock skew', () => {
+    /** Mint a proof as though this host's clock were `offsetMs` off from ours. */
+    const proofWithClockOffset = async (offsetMs: number): Promise<string> => {
+      vi.useFakeTimers()
+      try {
+        vi.setSystemTime(Date.now() + offsetMs)
+        return await createDpopProof(key, {
+          htm: HTM,
+          htu: HTU,
+          credential: CREDENTIAL,
+        })
+      } finally {
+        vi.useRealTimers()
+      }
+    }
+
+    it('accepts a proof from a holder whose clock runs slightly fast', async () => {
+      // Regression: without clockTolerance this is a hard 401, and only between real
+      // machines — it looks like an intermittent auth error.
+      const proof = await proofWithClockOffset(2_000)
+      await expect(
+        verifyAgainst(proof, { jkt: await dpopJktForKey(key) }),
+      ).resolves.toBeTruthy()
+    })
+
+    it('accepts a proof from a holder whose clock runs slightly slow', async () => {
+      const proof = await proofWithClockOffset(-2_000)
+      await expect(
+        verifyAgainst(proof, { jkt: await dpopJktForKey(key) }),
+      ).resolves.toBeTruthy()
+    })
+
+    it('still refuses a proof dated far in the future', async () => {
+      const proof = await proofWithClockOffset((MAX_PROOF_AGE_SEC + 60) * 1000)
+      await expect(
+        verifyAgainst(proof, { jkt: await dpopJktForKey(key) }),
+      ).rejects.toMatchObject({ code: 'BadDpopProofSignature' })
+    })
+  })
+
+  it('refuses a proof signed with an algorithm outside the allowed set', async () => {
+    // Signed directly rather than through createDpopProof, which refuses the key
+    // outright. The signature is valid and the thumbprint matches, so only the
+    // algorithm restriction stands between this proof and being honoured.
+    const rsaKey = await JoseKey.generate(['RS256'])
+    const proof = await rsaKey.createJwt(
+      { alg: 'RS256', typ: 'dpop+jwt', jwk: rsaKey.bareJwk },
+      {
+        jti: 'rsa-proof',
+        htm: HTM,
+        htu: HTU,
+        ath: await athFor(CREDENTIAL),
+        iat: Math.floor(Date.now() / 1000),
+      },
+    )
+    await expect(
+      verifyAgainst(proof, { jkt: await dpopJktForKey(rsaKey) }),
+    ).rejects.toMatchObject({ code: 'BadDpopProofSignature' })
+  })
+
+  it('refuses a token that is not a proof', async () => {
+    await expect(
+      verifyAgainst(CREDENTIAL, { jkt: await dpopJktForKey(key) }),
+    ).rejects.toMatchObject({ code: 'BadDpopProofSignature' })
+  })
+})

package/tests/lthash.test.ts

@@ -0,0 +1,97 @@
+import { describe, expect, it } from 'vitest'
+import { LTHASH_STATE_BYTES, LtHash } from '../src/index.js'
+
+const ZEROS = new Uint8Array(LTHASH_STATE_BYTES)
+
+describe('LtHash', () => {
+  it('starts as 2048 zero bytes', () => {
+    expect(new LtHash().state()).toEqual(ZEROS)
+    expect(new LtHash().isEmpty()).toBe(true)
+  })
+
+  it('add then remove returns to the zero state', () => {
+    const h = new LtHash()
+    h.add('a')
+    expect(h.state()).not.toEqual(ZEROS)
+    h.remove('a')
+    expect(h.state()).toEqual(ZEROS)
+  })
+
+  it('is order-independent', () => {
+    const a = new LtHash().add('a').add('b')
+    const b = new LtHash().add('b').add('a')
+    expect(a.equals(b)).toBe(true)
+    expect(a.digest()).toEqual(b.digest())
+  })
+
+  it('distinguishes different elements', () => {
+    expect(new LtHash().add('a').equals(new LtHash().add('b'))).toBe(false)
+  })
+
+  it('is a multiset — a double add does not cancel out', () => {
+    const h = new LtHash().add('a').add('a')
+    expect(h.isEmpty()).toBe(false)
+    h.remove('a')
+    expect(h.equals(new LtHash().add('a'))).toBe(true)
+  })
+
+  describe('state round-trips', () => {
+    it('resumes from persisted state', () => {
+      const a = new LtHash().add('a').add('b')
+      expect(new LtHash(a.state()).equals(a)).toBe(true)
+    })
+
+    it('treats nullish state as empty', () => {
+      expect(new LtHash(null).isEmpty()).toBe(true)
+      expect(new LtHash(undefined).isEmpty()).toBe(true)
+    })
+
+    it('rejects wrong-length state', () => {
+      expect(() => new LtHash(new Uint8Array(32))).toThrow(/must be 2048 bytes/)
+    })
+
+    it('does not alias the state it was built from', () => {
+      const state = new Uint8Array(LTHASH_STATE_BYTES)
+      state[0] = 0xff
+      const h = new LtHash(state)
+      state[0] = 0x00
+      expect(h.state()[0]).toBe(0xff)
+    })
+
+    it('does not alias the state it hands out', () => {
+      const h = new LtHash().add('a')
+      const state = h.state()
+      state[0] ^= 0xff
+      expect(h.state()).not.toEqual(state)
+    })
+  })
+
+  // How a caller stages a change without committing it: build from `state()`,
+  // mutate the copy, and leave the original where it was.
+  it('a hash built from another state does not share it', () => {
+    const original = new LtHash().add('a')
+    const staged = new LtHash(original.state()).add('b')
+    expect(original.equals(staged)).toBe(false)
+    expect(original.equals(new LtHash().add('a'))).toBe(true)
+  })
+
+  describe('digest', () => {
+    it('is 32 bytes, and sha256 of the zero state when empty', () => {
+      const digest = new LtHash().digest()
+      expect(digest).toHaveLength(32)
+      expect(Buffer.from(digest).toString('hex')).toBe(
+        'e5a00aa9991ac8a5ee3109844d84a55583bd20572ad3ffcd42792f3c36b183ad',
+      )
+    })
+
+    it('snapshot vector locks the algorithm', () => {
+      // 1024 lanes of u16 mod 2^16, elements expanded with BLAKE3 XOF at
+      // dkLen=2048, summed lane-wise. If this changes, persisted state must be
+      // recomputed.
+      const h = new LtHash().add('one').add('two')
+      expect(Buffer.from(h.digest()).toString('hex')).toBe(
+        'ae05cb6d224379d9710c290c8529945c5b0e0fde9ead30b9699057ce701c63e7',
+      )
+    })
+  })
+})