@atproto/space 0.0.0-spaces-alpha-20260818022935

package/src/credential.ts

@@ -0,0 +1,262 @@
+import { type Keypair, randomStr, verifySignature } from '@atproto/crypto'
+import { fromBase64, toBase64 } from '@atproto/lex-data'
+import { SpaceTokenError } from './error.js'
+
+/**
+ * How a space authority is addressed when acting as the space host: the service
+ * entry a delegation token and a client attestation name as their audience. Note
+ * this is the *audience*, not necessarily where requests are sent — an authority
+ * that publishes no such entry is still reached at its `#atproto_pds` endpoint.
+ */
+export const spaceHostAud = (spaceDid: string): string =>
+  `${spaceDid}#atproto_space_host`
+
+// The three token classes share a wire shape and differ only in who signs them,
+// who they're addressed to, and how long they live — hence data, not three impls.
+// A credential is multi-use across repo hosts, so it carries no aud; it is bound
+// to the holder's DPoP key instead (see dpop.ts).
+export const SPACE_TOKEN_TYPES = {
+  delegation: {
+    typ: 'atproto-space-delegation+jwt',
+    kid: '#atproto',
+    expiresInSec: 60,
+    requireAud: true,
+    requireCnf: false,
+    singleUse: true,
+  },
+  // An authority that publishes a dedicated `#atproto_space` key signs with it
+  // and passes that `kid`. Absent one, the space signing key is the account's
+  // `#atproto` key, which is the case for any authority hosted on a PDS.
+  credential: {
+    typ: 'atproto-space-credential+jwt',
+    kid: '#atproto',
+    expiresInSec: 7200,
+    requireAud: false,
+    requireCnf: true,
+    singleUse: false,
+  },
+  clientAttestation: {
+    typ: 'atproto-client-attestation+jwt',
+    kid: undefined,
+    expiresInSec: 60,
+    requireAud: true,
+    requireCnf: false,
+    singleUse: true,
+  },
+} as const
+
+export type SpaceTokenType = keyof typeof SPACE_TOKEN_TYPES
+
+// `sub` is the space URI, or the client_id for a client attestation.
+export type SpaceTokenPayload = {
+  iss: string
+  sub: string
+  aud?: string
+  iat: number
+  exp: number
+  jti: string
+  cnf?: { jkt: string }
+}
+
+export type SpaceTokenHeader = {
+  alg: string
+  typ: string
+  kid?: string
+}
+
+export type SpaceToken = {
+  header: SpaceTokenHeader
+  payload: SpaceTokenPayload
+}
+
+export const CLOCK_SKEW_SEC = 5
+
+export type CreateSpaceTokenOpts = {
+  iss: string
+  sub: string
+  aud?: string
+  dpopJkt?: string
+  expiresInSec?: number
+  kid?: string
+}
+
+export const createSpaceToken = async (
+  type: SpaceTokenType,
+  opts: CreateSpaceTokenOpts,
+  keypair: Keypair,
+): Promise<string> => {
+  const spec = SPACE_TOKEN_TYPES[type]
+  if (spec.requireAud && !opts.aud) {
+    throw new SpaceTokenError(`a ${type} token requires an "aud"`)
+  }
+  if (spec.requireCnf && !opts.dpopJkt) {
+    throw new SpaceTokenError(`a ${type} token requires a "dpopJkt"`)
+  }
+
+  const iat = Math.floor(Date.now() / 1000)
+  const header: SpaceTokenHeader = { alg: keypair.jwtAlg, typ: spec.typ }
+  const kid = opts.kid ?? spec.kid
+  if (kid) header.kid = kid
+
+  const payload: SpaceTokenPayload = {
+    iss: opts.iss,
+    sub: opts.sub,
+    ...(opts.aud ? { aud: opts.aud } : undefined),
+    ...(opts.dpopJkt ? { cnf: { jkt: opts.dpopJkt } } : undefined),
+    iat,
+    exp: iat + (opts.expiresInSec ?? spec.expiresInSec),
+    jti: randomStr(16, 'hex'),
+  }
+
+  const signingInput = `${jsonToB64Url(header)}.${jsonToB64Url(payload)}`
+  const sig = await keypair.sign(new TextEncoder().encode(signingInput))
+  return `${signingInput}.${toBase64(sig, 'base64url')}`
+}
+
+// Structural validation only, no signature check. This is as far as we go for
+// client attestations, whose key comes from the client's JWKS, not a DID doc.
+export const parseSpaceToken = (
+  type: SpaceTokenType,
+  jwt: string,
+): SpaceToken & { signingInput: Uint8Array; sig: Uint8Array } => {
+  const spec = SPACE_TOKEN_TYPES[type]
+
+  const parts = jwt.split('.')
+  if (parts.length !== 3) {
+    throw new SpaceTokenError('malformed token: expected 3 parts', 'BadJwt')
+  }
+  const [headerB64, payloadB64, sigB64] = parts
+
+  const header = decodeJsonPart<SpaceTokenHeader>(headerB64, 'header')
+  const payload = decodeJsonPart<SpaceTokenPayload>(payloadB64, 'payload')
+
+  if (header.typ !== spec.typ) {
+    throw new SpaceTokenError(
+      `wrong token type: expected "${spec.typ}", got "${header.typ}"`,
+      'BadJwtType',
+    )
+  }
+  if (typeof header.alg !== 'string' || !header.alg) {
+    throw new SpaceTokenError('missing token "alg"', 'BadJwt')
+  }
+  if (!payload.iss) {
+    throw new SpaceTokenError('missing token "iss"', 'BadJwtIss')
+  }
+  if (!payload.sub) {
+    throw new SpaceTokenError('missing token "sub"', 'BadJwtSub')
+  }
+  if (typeof payload.exp !== 'number') {
+    throw new SpaceTokenError('missing token "exp"', 'BadJwt')
+  }
+  if (spec.requireAud && !payload.aud) {
+    throw new SpaceTokenError('missing token "aud"', 'BadJwtAudience')
+  }
+  if (spec.requireCnf && !payload.cnf?.jkt) {
+    throw new SpaceTokenError('missing token "cnf.jkt"', 'BadJwtCnf')
+  }
+  if (spec.singleUse && (typeof payload.jti !== 'string' || !payload.jti)) {
+    throw new SpaceTokenError(
+      `a ${type} token requires a "jti" to be consumed by`,
+      'BadJwt',
+    )
+  }
+  if (type === 'clientAttestation' && payload.iss !== payload.sub) {
+    throw new SpaceTokenError(
+      'client attestation "iss" and "sub" must both be the client_id',
+      'BadJwtIss',
+    )
+  }
+
+  return {
+    header,
+    payload,
+    signingInput: new TextEncoder().encode(`${headerB64}.${payloadB64}`),
+    sig: fromBase64(sigB64, 'base64url'),
+  }
+}
+
+export type VerifySpaceTokenOpts = {
+  /** Passed `kid` so a verifier can honour the key id. */
+  getSigningKey: (
+    iss: string,
+    kid: string | undefined,
+    forceRefresh: boolean,
+  ) => string | Promise<string>
+  aud?: string
+  sub?: string
+}
+
+export const verifySpaceToken = async (
+  type: SpaceTokenType,
+  jwt: string,
+  opts: VerifySpaceTokenOpts,
+): Promise<SpaceToken> => {
+  const { header, payload, signingInput, sig } = parseSpaceToken(type, jwt)
+
+  const now = Math.floor(Date.now() / 1000)
+  if (now - CLOCK_SKEW_SEC >= payload.exp) {
+    throw new SpaceTokenError('token expired', 'JwtExpired')
+  }
+  if (opts.aud !== undefined && payload.aud !== opts.aud) {
+    throw new SpaceTokenError(
+      'token audience does not match this service',
+      'BadJwtAudience',
+    )
+  }
+  if (opts.sub !== undefined && payload.sub !== opts.sub) {
+    throw new SpaceTokenError(
+      'token subject does not match the requested space',
+      'BadJwtSub',
+    )
+  }
+  const didKey = await opts.getSigningKey(payload.iss, header.kid, false)
+  if (await matchesSignature(didKey, header, signingInput, sig)) {
+    return { header, payload }
+  }
+
+  // The signing key may have rotated since the one we hold was cached.
+  const freshDidKey = await opts.getSigningKey(payload.iss, header.kid, true)
+  if (
+    freshDidKey !== didKey &&
+    (await matchesSignature(freshDidKey, header, signingInput, sig))
+  ) {
+    return { header, payload }
+  }
+
+  throw new SpaceTokenError('invalid token signature', 'BadJwtSignature')
+}
+
+const matchesSignature = async (
+  didKey: string,
+  header: SpaceTokenHeader,
+  signingInput: Uint8Array,
+  sig: Uint8Array,
+): Promise<boolean> => {
+  try {
+    return await verifySignature(didKey, signingInput, sig, {
+      jwtAlg: header.alg,
+    })
+  } catch (err) {
+    throw new SpaceTokenError(
+      `could not verify token signature: ${errMsg(err)}`,
+      'BadJwtSignature',
+    )
+  }
+}
+
+const jsonToB64Url = (json: Record<string, unknown>): string =>
+  toBase64(new TextEncoder().encode(JSON.stringify(json)), 'base64url')
+
+const decodeJsonPart = <T>(b64: string, part: string): T => {
+  try {
+    return JSON.parse(new TextDecoder().decode(fromBase64(b64, 'base64url')))
+  } catch (err) {
+    throw new SpaceTokenError(
+      `could not parse token ${part}: ${errMsg(err)}`,
+      'BadJwt',
+    )
+  }
+}
+
+const errMsg = (err: unknown): string =>
+  err instanceof Error ? err.message : String(err)

package/src/dpop.ts

@@ -0,0 +1,166 @@
+import { EmbeddedJWK, calculateJwkThumbprint, errors, jwtVerify } from 'jose'
+import { randomStr, sha256 } from '@atproto/crypto'
+import type { Key } from '@atproto/jwk'
+import { toBase64 } from '@atproto/lex-data'
+import { CLOCK_SKEW_SEC } from './credential.js'
+import { DpopProofError } from './error.js'
+
+/**
+ * DPoP binding for space credentials (RFC 9449).
+ *
+ * A credential reads a whole space and is presented to every repo host in it. As a
+ * bearer token it would be a shared secret: a host given one to serve its own repo
+ * could replay it against every other host in the space.
+ */
+
+export const DPOP_PROOF_TYP = 'dpop+jwt'
+export const MAX_PROOF_AGE_SEC = 60
+const SIGNING_ALG = 'ES256'
+
+export type DpopProof = {
+  jti: string
+  jkt: string
+  htm: string
+  htu: string
+}
+
+export type CreateDpopProofOpts = {
+  htm: string
+  htu: string
+  /** Present when proving possession of a key bound to an access credential. */
+  credential?: string
+}
+
+export const createDpopProof = async (
+  key: Key,
+  opts: CreateDpopProofOpts,
+): Promise<string> => {
+  const jwk = key.bareJwk
+  if (!jwk) {
+    throw new DpopProofError('a DPoP proof requires an asymmetric key')
+  }
+  if (!key.algorithms.includes(SIGNING_ALG)) {
+    throw new DpopProofError(
+      `a DPoP key must support ${SIGNING_ALG}, got: ${key.algorithms.join(', ')}`,
+    )
+  }
+
+  return key.createJwt(
+    { alg: SIGNING_ALG, typ: DPOP_PROOF_TYP, jwk },
+    {
+      jti: randomStr(16, 'hex'),
+      htm: opts.htm,
+      htu: normalizeHtu(opts.htu),
+      ...(opts.credential !== undefined
+        ? { ath: await hashCredential(opts.credential) }
+        : undefined),
+      iat: Math.floor(Date.now() / 1000),
+    },
+  )
+}
+
+type DpopRequest = {
+  htm: string
+  htu: string
+}
+
+export type VerifyDpopProofOpts = DpopRequest &
+  (
+    | {
+        credential: string
+        jkt: string
+      }
+    | {
+        credential?: undefined
+        jkt?: undefined
+      }
+  )
+
+/** Checks everything but replay; the caller records the returned `jti` itself. */
+export const verifyDpopProof = async (
+  proof: string,
+  opts: VerifyDpopProofOpts,
+): Promise<DpopProof> => {
+  // EmbeddedJWK verifies against the proof's own `jwk` header; the thumbprint
+  // comparison below is what ties that key to the credential.
+  //
+  // Without the skew allowance a holder whose clock runs even slightly fast is
+  // rejected outright, since jose refuses an `iat` in the verifier's future.
+  const { protectedHeader, payload } = await jwtVerify(proof, EmbeddedJWK, {
+    typ: DPOP_PROOF_TYP,
+    algorithms: [SIGNING_ALG],
+    maxTokenAge: MAX_PROOF_AGE_SEC,
+    clockTolerance: CLOCK_SKEW_SEC,
+  }).catch((err) => {
+    if (err instanceof errors.JWTExpired) {
+      throw new DpopProofError(
+        `DPoP proof is expired: ${errMsg(err)}`,
+        'DpopProofExpired',
+      )
+    }
+    throw new DpopProofError(
+      `could not verify DPoP proof: ${errMsg(err)}`,
+      'BadDpopProofSignature',
+    )
+  })
+
+  const { jti, htm, htu, ath } = payload
+  if (typeof jti !== 'string' || !jti) {
+    throw new DpopProofError('missing DPoP proof "jti"')
+  }
+  if (htm !== opts.htm) {
+    throw new DpopProofError('DPoP proof "htm" does not match the request')
+  }
+  if (typeof htu !== 'string' || htu !== normalizeHtu(opts.htu)) {
+    throw new DpopProofError('DPoP proof "htu" does not match the request')
+  }
+  if (opts.credential !== undefined) {
+    if (ath !== (await hashCredential(opts.credential))) {
+      throw new DpopProofError('DPoP proof "ath" does not match the credential')
+    }
+  } else if (ath !== undefined) {
+    throw new DpopProofError(
+      'DPoP proof "ath" must be omitted when obtaining a credential',
+    )
+  }
+
+  // Present because jwtVerify used EmbeddedJWK.
+  const jkt = await calculateJwkThumbprint(
+    protectedHeader.jwk!,
+    'sha256',
+  ).catch((err) => {
+    throw new DpopProofError(
+      `could not compute DPoP key thumbprint: ${errMsg(err)}`,
+    )
+  })
+  if (opts.jkt !== undefined && jkt !== opts.jkt) {
+    throw new DpopProofError(
+      'DPoP proof is not signed by the key the credential is bound to',
+      'DpopKeyMismatch',
+    )
+  }
+
+  return { jti, jkt, htm, htu }
+}
+
+/** The RFC 7638 thumbprint of a DPoP key. */
+export const dpopJktForKey = async (key: Key): Promise<string> => {
+  const jwk = key.bareJwk
+  if (!jwk) {
+    throw new DpopProofError('a DPoP key must be asymmetric')
+  }
+  return calculateJwkThumbprint(jwk, 'sha256')
+}
+
+// Strips query and fragment (RFC 9449 §4.2), so one proof covers any query on a path.
+const normalizeHtu = (url: string): string => {
+  const parsed = new URL(url)
+  return parsed.origin + parsed.pathname
+}
+
+const hashCredential = async (credential: string): Promise<string> => {
+  return toBase64(await sha256(credential), 'base64url')
+}
+
+const errMsg = (err: unknown): string =>
+  err instanceof Error ? err.message : String(err)

package/src/error.ts

@@ -0,0 +1,38 @@
+export class SpaceTokenError extends Error {
+  constructor(
+    message: string,
+    public readonly code:
+      | 'BadJwt'
+      | 'BadJwtType'
+      | 'BadJwtIss'
+      | 'BadJwtSub'
+      | 'BadJwtAudience'
+      | 'BadJwtCnf'
+      | 'BadJwtSignature'
+      | 'JwtExpired' = 'BadJwt',
+  ) {
+    super(message)
+    this.name = 'SpaceTokenError'
+  }
+}
+
+export class DpopProofError extends Error {
+  constructor(
+    message: string,
+    public readonly code:
+      | 'BadDpopProof'
+      | 'BadDpopProofSignature'
+      | 'DpopProofExpired'
+      | 'DpopKeyMismatch' = 'BadDpopProof',
+  ) {
+    super(message)
+    this.name = 'DpopProofError'
+  }
+}
+
+export class RepoVerificationError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'RepoVerificationError'
+  }
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export * from './credential.js'
+export * from './dpop.js'
+export * from './error.js'
+export * from './lthash.js'
+export * from './repo-commit.js'
+export * from './sync/index.js'
+export * from './types.js'
+export * from './util.js'

package/src/lthash.ts

@@ -0,0 +1,80 @@
+import { blake3 } from '@noble/hashes/blake3'
+import { sha256 } from '@noble/hashes/sha256'
+
+const LANES = 1024
+const LANE_BYTES = 2 // @NOTE cannot change without reworking the Uint16Array impl
+export const LTHASH_STATE_BYTES = LANES * LANE_BYTES // 2048
+
+/**
+ * A homomorphic set hash. Each element expands to 1024 little-endian u16 lanes
+ * which are summed into the state mod 2^16. Addition and subtraction commute, so
+ * the state depends only on the current set, not on insertion order.
+ */
+export class LtHash {
+  // Two views over one buffer: bytes for I/O, lanes for u16 arithmetic (which
+  // wraps mod 2^16 on its own).
+  private readonly bytes: Uint8Array
+  private readonly lanes: Uint16Array
+
+  constructor(state?: Uint8Array | null) {
+    if (state && state.length !== LTHASH_STATE_BYTES) {
+      throw new Error(
+        `LtHash state must be ${LTHASH_STATE_BYTES} bytes, got ${state.length}`,
+      )
+    }
+    const buffer = new ArrayBuffer(LTHASH_STATE_BYTES)
+    this.bytes = new Uint8Array(buffer)
+    this.lanes = new Uint16Array(buffer)
+    if (state) this.bytes.set(state)
+  }
+
+  add(element: string): this {
+    const lanes = expand(element)
+    for (let i = 0; i < LANES; i++) {
+      this.lanes[i] += lanes[i]
+    }
+    return this
+  }
+
+  remove(element: string): this {
+    const lanes = expand(element)
+    for (let i = 0; i < LANES; i++) {
+      this.lanes[i] -= lanes[i]
+    }
+    return this
+  }
+
+  // The full state, for persistence.
+  state(): Uint8Array {
+    return new Uint8Array(this.bytes)
+  }
+
+  digest(): Uint8Array {
+    return sha256(this.bytes)
+  }
+
+  isEmpty(): boolean {
+    for (let i = 0; i < LANES; i++) {
+      if (this.lanes[i] !== 0) return false
+    }
+    return true
+  }
+
+  equals(other: LtHash): boolean {
+    for (let i = 0; i < LANES; i++) {
+      if (this.lanes[i] !== other.lanes[i]) return false
+    }
+    return true
+  }
+}
+
+// Expand to 1024 u16 lanes with BLAKE3 in XOF mode.
+const expand = (element: string): Uint16Array => {
+  const expanded = blake3(new TextEncoder().encode(element), {
+    dkLen: LTHASH_STATE_BYTES,
+  })
+  // Copy: the result may be a view at an offset a Uint16Array can't straddle.
+  const buffer = new ArrayBuffer(LTHASH_STATE_BYTES)
+  new Uint8Array(buffer).set(expanded)
+  return new Uint16Array(buffer)
+}