Commit 369961d

- **A local media purge refuses an id that is not one path segment.** On a

server with `PERSIST_TO_LOCAL_STORAGE=true`, a crafted document id could

reach another document's media folder, or a folder outside the storage root.

The purge now logs a warning and deletes nothing for such an id. The

WebSocket room name and `PUT /api/documents/:docId` now refuse an id outside

`[A-Za-z0-9_-]`, 1 to 100 characters. The PUT answers `400`, and the

WebSocket counts `ws_auth_rejections_total{reason="invalid-document-id"}`

([#426](https://github.com/docs-plus/docs.plus/issues/426)).

- **A signed-in WebSocket closes when its access token expires.** At the

token's `exp`, the server closes the socket with code `4408`. The webapp

reconnects with a fresh token, so `onAuthenticate` checks the identity again.

A token already past `exp` is refused like an invalid one. Each signed-in tab

reconnects about once per token lifetime, which is 1 hour by default

([#430](https://github.com/docs-plus/docs.plus/issues/430)).

- **Local `deleteByPrefix` refuses an id that is not one path segment** (`src/lib/storage/storage.local.ts`, #426). A containment check alone passes `a/../<id>`, which names another document's folder. The refusal warns and returns, because the purge RPC has already run. Keep this check in the adapter, never in `media.service.ts` or the purge service. `onAuthenticate` and `PUT /api/documents/:docId` refuse such ids too, through `documentIdField` (`src/schemas/hypermultimedia.schema.ts`). The upload route enforces the same rule, so all three agree on which ids can own media. Do not narrow it to the 19-character `documentIdSchema`, because nobody has counted the stored ids that rule would lock out.

- **A signed-in socket closes with `4408` at its token `exp`** (`TokenExpiryExtension`, `src/extensions/token-expiry.extension.ts`, #430). It closes the socket, never `connection.close()`. That call sends a document Close, and the provider then keeps the socket open and never reconnects. The reconnect re-runs `onAuthenticate`. A delete or a sign-out elsewhere should then take effect within one token lifetime plus the 60 s verify cache. A ban can take close to two lifetimes, because a tab may hold a fresh token minted just before the ban. Neither case is verified on the local stack yet. `onAuthenticate` refuses a token already past `exp`, because the 60 s verify cache can return one, and admitting it would loop the reconnect. The timer rides `context`, and `onDisconnect` clears it. A `DirectConnection` never fires `connected`, so it gets no timer. If Supabase Auth is down at `exp`, the reconnect degrades to anonymous, and a Private document's owner is denied until Auth recovers. That trade is accepted.

docIdParamSchema,

zValidator('param', docIdParamSchema, houseEnvelopeHook),

import { TokenExpiryExtension } from '../extensions/token-expiry.extension'

extensions.push(new TokenExpiryExtension())

import type { connectedPayload, Extension, onDisconnectPayload } from '@hocuspocus/server'

const TOKEN_EXPIRED_CLOSE_CODE = 4408

const MAX_TIMER_MS = 2 ** 31 - 1

interface TokenExpiryContext {

tokenExp?: number

tokenExpiryTimer?: ReturnType<typeof setTimeout>

export class TokenExpiryExtension implements Extension {

// Close the socket, never connection.close(): that sends a document Close, and the

// provider then keeps the socket open and never reconnects. A socket close makes it

// reconnect with a fresh token, so onAuthenticate decides the identity again.

async connected({ context, connection }: connectedPayload) {

const ctx = context as TokenExpiryContext

if (typeof ctx.tokenExp !== 'number') return

const delay = Math.min(Math.max(0, ctx.tokenExp * 1000 - Date.now()), MAX_TIMER_MS)

ctx.tokenExpiryTimer = setTimeout(() => {

connection.webSocket.close(TOKEN_EXPIRED_CLOSE_CODE, 'Access token expired')

}, delay)

}

async onDisconnect({ context }: onDisconnectPayload) {

clearTimeout((context as TokenExpiryContext).tokenExpiryTimer)

}

export default TokenExpiryExtension

import { decodeJwtClaims, isConnectedAppToken } from './lib/jwtClaims'

import { documentIdField } from './schemas/hypermultimedia.schema'

// The first edit writes a row under this name, and a purge later deletes media by it.

if (!documentIdField.safeParse(documentName).success) {

wsAuthRejectionsTotal.inc({ reason: 'invalid-document-id' })

throw new Error('Invalid document ID')

}

// Outside production the caller falls back to anonymous instead.

const refuseInvalidToken = (): void => {

if (!isProd) return

wsLogger.info({ documentName }, 'Rejecting invalid/expired token')

wsAuthRejectionsTotal.inc({ reason: 'invalid-token' })

throw new Error('Invalid authentication token')

}

let tokenExp: number | undefined

case 'user': {

// The verify cache can return a token past its exp. Admitting it would arm

// a zero-delay expiry close, and the tab would reconnect in a loop.

const claimedExp = decodeJwtClaims(tokenData.accessToken)?.exp

const exp = typeof claimedExp === 'number' ? claimedExp : undefined

if (exp !== undefined && exp * 1000 <= Date.now()) {

refuseInvalidToken()

wsLogger.warn({ documentName }, 'Token already expired - allowing in dev')

break

}

tokenExp = exp

}

refuseInvalidToken()

return { user, slug, documentId: documentName, deviceType, tokenExp }

const root = storageRoot()

const dirPath = path.resolve(root, documentId)

if (!documentId || path.dirname(dirPath) !== root || path.basename(dirPath) !== documentId) {

storageLocalLogger.warn(

{ documentId },

'Refusing a media purge for an id that is not one path segment'

)

return

}

// `force` makes a missing dir a no-op, so a reaper retry is safe.

import { documentIdField } from './hypermultimedia.schema'

export const docIdParamSchema = z.object({ docId: documentIdField })

export const documentIdField = z